I cloned the repository. It runs smoothly in the home network: http://www.mistelberger.net/opensuse-guide.png
Comrades, my apologies for so many ‘itty-bitty’ responses. It’s not lack of respect, just time-zone difference and my fading brain.
I agree with karlmistelberger, issues like btrfs and btrfs maintenance, cry out for a ‘general user guide’ for both old and new ‘general users’.
The ‘unofficial guide’ is aimed at new users. Perhaps similar basic context setting ‘unofficial’ guides for the ‘general user as administrator’ would be useful?
Apart from bug reporting, my only contribution to ‘development’ has been in translation and editing (plain English). I would be happy to help, if I can.
[QUOTE=karlmistelberger;3037365] https://github.com/openSUSE/openSUSE-docs-revamped-temp /QUOTE]
Well, that brought a smile. Why am I surprised?
Looks like a good start, but hey, there’s room for improvement. A bit too loose and apologetic in tone and far too many highfalutin words.
Shakespeare had the pit, Marx had lots of angry letter writers; so where do I sign up? How does it work? Who’s who? Is there a mailing list for chit-chat? [essential]
I know next to nothing about Snapper - I am a “confused” general user and very short of disk space - so Snapper has been no help to me. But I live in hope.
So, for a brief example - the draft docsays:
“Snapper is a tool for filesystem snapshot management. Snapshots are fully defined state in your system at one point in time, just like a photography is a fully defined moment in a movie, for example. Snapper is able to create, delete and compare snapshots, and to undo changes that occurred between snapshots. It is thus a powerful maintenance tool that allows you to ‘cheat’ the flow of time: if you run into an outstanding bug you can use Snapper to rollback to a past snapshot, typically one where the bug didn’t exist yet. Or if you’ve already moved to a past snapshot, you are able to switch move to a snapshot that lies in the ‘future’ relative to it.”
Phew, those rabbits are running everywhere …
It could use plain English, and [stuff in sq brackets excluded] say something like:
Snapper is a BTRFS [link] management tool that gives users more control of the state of their B-tree file system. It does this by saving maps or “'snapshots” of the state of the file system from time to time, as determined by the user. The user can then compare and delete saved “'snapshots” [better explain how to do this somewhere] and can boot the system in a previous state by selecting a saved “snapshot” from the GRUB [link] menu at boot time. This means that should a B-tree file system become corrupted by a bug or other system change error, the user can boot the system from a “snapshot” taken before the bug or error was introduced.
[quote="“Tallowwood,post:24,topic:146030”]
Documentation is essential. In the nineties I worked on core design and fuel management at what is now Framatome Erlangen. Software was maintained with ClearCase, initially released by Atria in 1992. Synchronization between the numerous sites was done manually.rotfl!
When vacationing in the Austrian Alps during the Christmas and holiday season 1995 I caught a really bad cold and was unable to go for skiing. I spent the day with a printed copy of Atria’s ClearCase MultiSite manual. The thin volume was an excellent piece of documentation. In the evening I was done with a write-up and resumed skiing on the next day. Upon returning from vacation I convinced management to buy MultiSite. Deployment at local test sites was as easy as could be. The Richland, WA facility was the last site and deployment was complete in August 1996. When participating in HP’s Fortran 90 beta program they signed a non disclosure agreement, we shipped a replica of our test bed to Chelmsford, MA. They had a live experience of Erlangen’s testing with no communication overhead until first release in autumn 1996.
Participation in openSUSE User Documentation is easy. Get familiar with the basics of git Clone their repo and do some exercise. When comfortable with git basics annotate your local version as desirable. Anything you do can be undone without further hassle. Nobody will be annoyed by your testing. For submitting your contributions issue a pull request. Even if they won’t pull in your contribution you will enjoy it at your home network.
I’ll have a look at git and see if I can make a contribution. Thanks for taking time to respond.
You are welcome. Structure matters as does language and style: Introduction :: Fedora Docs
It’s only been two days but I find it is difficult to engage with any openSUSE documentation project as a ‘general user’.
The main stumbling blocks are: a) lack of a clear contact, lead author (maintainer) or descriptive entry point; b) lack of coherent target audience definitions and mission statements; c) lack of a style guide [Does the SUSE Style Guide apply? It looks good, though it preferences USofA English.); d) confusion between promotion and user manual objectives; e) steep technical barriers to entry (git, mkdocs, etc.); and, f) a ‘laconic’ approach to admin and coordination (no meetings for months, unstructured Telegram group chats, accidental repo deletions). Is the openSUSE ‘contact’ project still alive? There seems to be little activity, and no ‘documents’ group.
The release notes could be better, particularly style, tone and grammar. Why choose to preface them with wishy-washy waffle: “openSUSE Leap is a free and Linux-based operating system for your PC, Laptop or Server. You can surf the Web, manage your e-mails and photos, do office work, play videos or music and have a lot of fun!” Surely what is needed is a plain English summary of what the document is, not a pointless, ‘laconic’ promo that is irrelevant, archaic, distracting and impertinent.
That is just odd. I am more concerned about the tendency for lax targeting, poor style and bad grammar to introduce ambiguity and confusion in the ‘technical’ text.
For example, in the first parra, describing changes to the update repo structure we find: “We recommend you to use them. [colloquial, bad grammar, confusing - say ‘recommend that you use them’] New update repository definitions [meaning? is ‘repository definition’ defined? does it refer to the repo reference name, the description, the technical structure?] for openSUSE Leap 15.3 will be additionally supplied [dubious grammar, ambiguous - is ‘also’ or ‘supplementary’ intended?] via a 0day maintenance update [jargon, non-word, meaning?] of the openSUSE-release package. The update will be delivered via the traditional repo-update maintenance channel [confusing, is ‘traditional’ or ‘channel’ needed at all?].” We do learn that there are now two extra repos to worry about, and why; and that there are some vaguely described ‘automatic’ processes to include these in the zypper repo list; but, we don’t learn what a user may need to do to find or add them, or what to do if those ‘automatic’ processes are not triggered or fall over. Perhaps we should.
The SUSE Style Guide gives good advice: ‘…define the target audience of your documentation. Adjust tone, style, and technicality of the text based on the intended audience. Keep in mind that not all facts that seem obvious to you will be obvious to your readers.’
p.s. this is just chit-chat, don’t let it distract from useful work on technical forums.
Instead of complaining, maybe fix the problem yourself?
You are free to improve the documentation as they are freely available and you can submit corrections. Remember that not everyone who writes documentation is an English major - that is just arrogant presumption.
I rest my case.
Perhaps add William Golding’s 1954 novel “Lord of the Flies” to the suggested reading list, along with the excellent SUSE Style Guide.
The starting point is Join our team and help us improve the openSUSE learning experience!
… a group of volunteers has taken up the task of improving the learning experience for all users – regardless of their experience and expertise.
- For new users, we want to make sure they can identify what best fits their needs, get the right tools and seamlessly take over from the post-installation screen.
- For experienced users, we want to provide them with detailed documentation that is easy to update, so that their experience and expertise can benefit others.
We believe that from engineers to end-users, everyone deserves to have confidence not only in their OS, but in the way they’re using it. A chain of trust like this is made of a user-friendly documentation where technical details are balanced with evidence-based good practices.
See also The construction site for the upcoming Leap and Tumbleweed documentation
Create an account at github.com and join the discussion as described at Contributing
Familiarity with git basics helps a lot: Fork a GitHub Repository & Submit a Pull Request
Useful resource for technical writers - video talk and essay by Paul Brown - far better words that I can bring to a complex topic.
The Baseline - Or Writing Technical Stuff for Non-Technical Readers, Paul Brown, Kockatoo Tube (video), 2020-10-21
Technical writers sometimes have to write for end users. This talk looks at ways to get the message across.
https://tube.kockatoo.org/w/5t8kfrkCBTwBb4QG7GK52F
This talk was delivered at the Write the Docs - Prague conference in October 2020.
Full article at https://quickfix.es/2020/10/the-baseline/
–
Grateful thanks to all who contribute and support the openSUSE project.
Feedback wanted
This documentation is curated and maintained by openSUSE volunteers. The contents offered here must be distinguished from the Leap documentation, also available at https://doc.opensuse.org. In contrast to this documentation, Leap manuals inherit the contents from, and closely follow the presentation of, SLE manuals – a commercial product offered by SUSE Because of this difference the reader should be aware of the following caveats:
- The present documentation is the work of volunteers – not SUSE employees – working under the Free and Open Source Software tradition. Our best efforts notwithstanding, inaccuracies and oversights are possible.
- Disclaimers and admonitions provide as safe as possible a path for the reader to follow. Yet be aware that openSUSE contributors cannot support every software feature or combination of software.
- openSUSE Tumbleweed follows a rolling release model, with software and procedures evolving significantly faster than their equivalents for openSUSE Leap. Thus contents presented here may occasionally be one version behind the version available in Tumbleweed.
**In response to these caveats we expect the reader to help us identify typos, omissions, inaccuracies or outdated contents by reporting them, ideally along with suggested improvements.
In advance we thank you and will try to response to your submissions as quickly as possible. We hope you enjoy our contents.