|| This EngineRoom topic is TWiki.org specific and is not part of the official TWiki distribution
TWiki Docs Style Guide
What it is...
Begun long ago - end of Sep last year - just after starting with docs, I put this together. Not much, but doesn't need much, either. But since there was no one else, I didn't keep it up, though I should've. Anyhow, it's started, and useful if completed to a base usable level. And used...
Obviously, a docs style manual could go on forever. But there's a sensible minimum amount of structure that's worth...documenting. Advantages:
- easier to get new help on board
- can create doc forms that developers can easily fill in
- easier for end-user to use docs: more people do more with TWiki
- looks good! makes better impression all round
Two-level modular structure (Chapter:Section)
Organized by Chapter and Section, with two additional levels of Sub-Sections, for a maximum of four levels:
. The basic modular unit of info is a Sub-Sub-Section - Level 4. Numbering is optional for Levels 3 & 4.
are used for material that would disrupt the flow if included in the body of the manual, and is supplementary content. Includes: file lists, technical specifications, articles, links lists, general how-to tips, etc. Anything not strictly to do with installing, configuring and maintaining the standard distribution package.
- Anything referred to in several modules goes in an appendix.
- Appendices are numbered in the same way as other modules.
- figure out use of
%INCLUDE% and links with appendices:
- when to use
%INCLUDE% vs hyperlink
- when to create appendix vs referring to (
%INCLUDE% or hyperlink) from another (primary) location in the body of the manual vs writing alternate versions (sub-sets of info) for specific contexts
Chapter content format
1. Chapter 1 ...
One-line chapter summary
Summary of contents; suitable for extract.
1.x Known Issues...
Optional; last section of Chapter; includes
Current Limitations; usually no sub-sections
A. TWikiRef A: Xxxxx...
Text formatting conventions
Not fully worked out, but so far:
monospace is used for:
- code snippets and listings
- API and language elements, like method and property names
- file/path/directory names
- HTML, TWikiNotation and other mark-up tags
- text to be entered by the user
- variables and placeholders
- italic is used for:
- titles (books and publications in other media)
- Use as little as possible in final docs - harder to read.
- bold italic for internal notes; for extreme emphasis in docs
- bold type is used for:
- TWiki general emphasis: TWiki,
[Action] - bold monospaced in square brackets for TWiki onscreen buttons and action links only
[Edit] [Attach] [Preview Changes] [Rename/move] OR
- capitalization, spacing exactly as they appear onscreen
- WikiWords in general are USUALLY left active, even on its own topic - ie: no use of the <nop> tag.
- when there's just too many
- in headings
Highlighting & special notation
- Highlights important items - replaces NOTE: and NOTE:
- is for internal notes that shouldn't appear in final docs
For examples. This is just a highlight device: other formatting still
applies. Use of CSS for background degrades; inset alone still helps.
Ignore the ALT tooltips - they're not defined for this use
- = important note, alert, warning, attention...
- = notable note/help/FAQ/
- = strictly a tip:
- Combinations: ? Combinations of the main three icons don't make sense, so single icons only should be used, with restraint.
- Who's the target reader? Different of User's Guide and Ref Manual
- TWikiDoc style at this point is simply about defining the audience and attempting to satisfy it with clear info; there's not much writing
- Easiest way to discuss style is through examples, like links to sites that illustrate ideas good and bad, for design, navigation, editorial style
Warning: Can't find topic Sandbox.TWikiDocLookups
- What dictionary? Pretty loose. For now, http://dictionary.com - meta searches 4-5 English dictionaries, and a s/w dict (forget name)
- Style manual: will link to one, for grammar, syntax, usage...
- issue: site=>web=>topic terminology
Updating TWiki Docs (Procedure for Editors)
1.0 Public Changes and Comments
Any TWiki.org member can edit docs topics in the TWiki web.
- Comments: Per topic feedback - comments, questions, suggestions - are posted in a Comments section at the end of the page.
- Changes: Corrections - spelling, grammar, simple rewrites of awkward sentences, corrections and additions to instructions - are made directly to the main text. Proposed changes can also be posted in Comments, to be checked out by an official TWiki Docs scribe.
2.0 Developer Documentation
A new TWiki feature, approved as completed and in Beta release, is usually first written up by the developer. Completely new/rewritten features appear as a new or renamed docs topic. Some enhancements may also require new topics, also, changes to related topics.
To keep things simple, entering a new feature should include updating its current Codev page as well.
- Decide what to replace or edit on an existing topic, or start a new topic with the feature name from Codev (eg: TWikiForms). You don't have to edit the TWiki contents or create other links.
- Use the most similar docs content as a template; enter copy.
- If you're cloning changes in TWikibeta, replace only the exact section, not the whole page; for a new page, create and paste.
- add the note that documentation is needed to the OutstandingIssues field.
3.0 TWiki Docs Final Editing
Someone approved as a docs editor, with access to TWikibeta - Mike,...? - should complete a full docs update daily, every day, two days max.
- In Codev, check summaries of DocsRequested and DocsToDo in Codev.
- TODO: check for new page or modified page in TWiki web; if not found, change to DocsRequested.
- REQUESTS: check dev page: post questions if not clear; change to DocsToDo if straightforward; decide to do immediately or sked; post update on page.
- In TWiki, check each changed docs page, back to last Editor update, including any new pages, editing as necessary.
- Comments: Comments are deleted, copyedited, replied to, or moved (eg: to Support) depending on relevance and value to the page they're on. Anything that should update the docs is entered in the main text.
- CREDITS: 0ne-time typos fixes and minor sentence rewrites are not credited. All other useful comments, and comments used to update docs or otherwise directly change docs (eg: suggesting a new symbol), are either acknowledged in the topic's group credit, the main TWiki docs group credit (for more minor contributions, like regular typo corrections), or in special cases (eg: a documented workaround) credited where it appears.
- REPLIES: Ask for more info; supply an answer to a specifically docs-related question/comment; if not directly docs related, but relevant, note that post should be moved to proper web - Codev, Support, Plugins; move/remove new and noted but not moved off-topic posts and leave note; note that post was incorporated in docs.
- Updates: Changes made directly to the docs text, by a site member or developer, are edited. Major changes - particularly new pages - are also updated in the docs contents and on related pages.
- Copyedit; fit to docs topic format. Leave warning notes if anything needs checking. If a new page should be a section of an existing topic, move it and delete original page.
- For new pages and major updates, rename page if necessary using: feature name; descriptive title (eg: ManagingWebs); Appendix plus one of the previous two.
- For new and renamed pages, edit or enter in docs contents page. If necessary, add link or link-plus-description in directly related docs topics.
- For new and rewritten features - anything other than bug fixes and minor changes - check/add to Appendix B: TWiki Dev Timeline. Use FeatureCompleted date. Doublecheck with Peter on credits.
- For major features with developer docs, credit page with developer, then editor. Depending on how much rewriting, leave developer credit if/until page is pretty well completely revised from original, then remove (possibly over several updates). Include developer in topic and docs group credits.
For minor updates, credit as for Comments.
- In Codev, change DocsToDo to FeatureDocumented, and add docs link to dev page.
- Update in TWikibeta: Copy entire TWiki topic and paste into same-named TWikibeta topic - create if necessary. Remove extra INCLUDES and any comments at top and bottom: paste and delete, or don't select in copy.
That's it (in twice the words)!
Few other things to go...
...for a core manual, including:
- internal (in-manual) and external links
- pop-up or target blank tag
- Interwiki doesn't always look too good
- graphics/screen snaps==
- format for step-by-step instructions
- need stylesheet: type, h1-h4, margins, indents, colors, spacing.....
Updating support system:
And, probably using forms, an automatic system for filing additions and updates to beta doc (request tracker/trouble ticket style). Anyone or authorized-only can:
- fill out doc add/update form
- mod is posted in suggested location
- check/edit/approve topic
- manually integrate topic into docs
to tie in Support - easy way to tag stuff useful for docs, particularly with non-tech stuff...
- evening out ref pages
- use of quotes
- final proofing procedure w/ easy sign-off
- proofing and final read for continuity & style
- proofing for technical details
- proofing for TWiki formating
- overall check of final compiled production version
-- Contributors: MikeMannix
Excellent idea to have guide how to contribute to doc in common style. IMHO this useful document should be mentioned directly in WebHome
, right where Reference manual starts?
- 11 Feb 2002
I would discourage the use of the Latin abbreviations; they are frequently written with incorrect punctuation, and sometimes interchanged. So instead of i.e.
, use that is
. Instead of e.g.
, use for example
. Complete words are clearer than abbreviations.
Also, it would help to have a uniform way of representing the em-dash in ASCII. I tend to use two -- like this -- because an actual em-dash is quite long. However, consistency is more important than the actual number.
- 12 Feb 2002
Ponch! (I have a feeling I owe you something...?) Regarding ie
- the last sort of detail one would imagine being disucssed in TWiki docs, huh?! - I agree it's an issue. Let's decide. I find the full form, i.e.
too long, I'd suggest using a colon ie:
. As for eg:
is an "Americanization" that's used but not even in all dictionaries; still, it's also a valid abbreviation for example. And ALWAYS writing out for example
and that is
is bit limiting. So, for ultimate simplicity and clarity, as conventions for TWiki Docs only, I suggest:
- never use i.e. - Latin is dead...; spell it out or handle any other way, and shouldn't be used often anyhow, not the clearest constructon
- use ex: as abbreviation for example; it's not a version of e.g., it's our abbreve of example (which can also be spelled out, ex: "for example"; "Example:")
As for em
dash stuff, dunno. Two dashes with spaces on either side looks better, but don't dashes usually split on word wraps? That looks confusing. TWikiFormattingRules
, either, but three dashes at start of line is a rule. In email, I still like monospace and use single dashes 'cause of the wrap. Maybe stick to that? Or are there other processing considerations?
This is soothing, mine-numbing in a pleasant way.
- 07 Mar 2002
When training my TWiki users, I am too lazy to develop my own beginner's tutorial/guide. Instead, I am pointing to TWiki pages. And my experience (and I bet yours, too) suggests me that most users hate
reading docs. I even read research somewhere that 90% of users prefere not
to read docs, and ask local expert instead, or do it some cumbersome way without learning. See research why users never read manuals: The Paradox of the Active User
So in ideal word, we should develop docs (comprehensive, informative, readable) for these audiences (IMHO):
- guide for newbie TWiki user (person not interested in reading about advanced features right now);
- readable tutorial for a person who is advanced TWiki user, but not TWiki admin;
- reference manual for advanced user, willing to read all details;
- TWiki admin. - has separate domain.
Obviously, each audience has different informational needs, and requires different approach. It will be nice to have separate documents (TWiki pages) for different audiences, but I am afraid it is too much work for volunteers like MikeMannix
(and I promise to help!).
For newbie, it is IMHO very important consciously and actively hide as much info as safely possible, just show a link that more info is available. Assume newbie does not want to read, and prefer somebody preselect for them only important stuff. See also Jakob Nielsen's Alertbox article: How Users Read on the Web
and Are Users Stupid?
Obviously deciding which part is advanced is rather subjective. But we can talk about which part belong where, and why.
Admin is different from advanced user. Advanced user knows basics, is willing to learn new tricks (remember 90% of users are reluctant to spend time learning new skills, and will remain newbies), but his/her job is not set rights to others or install new features. So admins have separate topics, and if somebody is admin, we can expect him/her to be advanced, and willing/able to read docs. And for newbie admins there is TWikiAdminCookBook
, which probably should be better named GuideForNewTWikiAdmin
Remember, most participants here at TWiki have mindset of advanced user, even if they are newbies in TWiki. They are willing and enjoy learning new ways to do things. Most users are just not wired this way, and there is nothing we can do about it. No doc format will change that. The only way we can persuade to read couple pages of docs is, pages should be short. Assume that newbie's interest is lost and will stop reading the moment s/he thinks "I will _never
use this feature"._ After cca 3 pages like that, s/he does not believe you TWiki is simple to use.
IMO instead of creating separate sets of documents for each audience, we can:
- For Newbie: have couple of pages for newbies only, with only basic stuff. No advanced stuff on these pages, only link.
- For Advanced users: I propose to have couple lines summary on top of each page, distinguished by color. Example: Jakob Nielsen's Alertbox article at useit.com: Content Creation for Average People.
- have nice big graphic icons in pages where basic and advanced information is placed together. As an avid cross-country skier:
- this is easy, basic, for newbies:
- this is steep, for advanced users: and newbies can safely skip rest of the page, or until next "easy" sign.
BTW, wikis are not mentioned in article above, not even in Readers' Comments
. Maybe should be mentioned?
If we want to create consistent documentation, we need to use consistent terminology. One issue discussed somewhere is, how we want to call page. TWiki uses topic,
but I heard most other wikis uses just page.
I personally prefer page,
this is how whole web calls it, why Twiki needs be different? Or is here some subtle difference? See also discussion in TWikiTopics
- looks like it's not only me.
I am not sure how to approach issue of creating consistent terminology. My experience (I did translated couple of manuals from english) suggests me, we need to make list of terms in question, talk about possible wordings to name these terms, associations and usage in other systems/problem areas/languages, and also CoreTeam
preferences. One nice solution might be to have separate web, and one topic per term. This might be an overkill, maybe single topic (like TWikiGlossary
) with %TOC% on top will be sufficient. Or we can start with single topic for now, and we'll see. Or something else.
Looks like MikeMannix
is final authority in terminology for docs, or is it CoreTeam
? How to make sure new improved docs is included in next release?
I am not freeloader. I am willing to help with docs. I am not good admin, and need somebody will put to gether for me SimplerTWikiDistribution
, with SimplerDefaultTemplates
, so I can deploy it with all docs in distribution. Like everybody else, I am solving my own problems. I am just lazy (in Larry Wall's sense) to answer all questions about docs, so I want it to be as good as possible.
- create set of documentation pages for newbies only, and actively hide advanced stuff
- on other pages should be obvious which parts are easy, and which are advanced (and not required in first reading)
- have summary with colored background on top of the page
- think (and do something) about consistent terminology
Thank you for your attention.
- 28 Feb 2002
>For Newbie: have couple of pages for newbies only, with only basic stuff. No advanced stuff on these pages, only link.
That's why I submitted a simpler version of WelcomeGuest#DocsComments
, which then leads a new user to StartingPoints
. (I'd like to simplify the topics linked in StartingPoints
- 28 Feb 2002
I agree with...everything. Actually, Peter's list of versions seems a little daunting to consider right now. I wrote out somewhere a plan of sorts to collapse what are now called User Guides into a very few quick ref style pages with identical format. Right now, there's a kind of jumble of styles and overlapping info in the intro pages, with a couple of entire full admin docs pages tossed in as well.
People definitely don't like reading docs. But I think they actually don't like being SEEN or TELLING anyone about it (in case they still
don't get it?). People seem to like to REJECT new things, but as soons as there's a perceived benefit, simple, usable docs will probably be used.
A neatly formatted matrix - a table with a few subtle but peppy icons - like the TextFormattingRules
edited and designed - seems to work well. Clear sections are important, separations between each line, brief paragraphs, and mostly this sorta thing:
- | Handling text is easy. | Handling text is easy! |
Also, User Guide admin customization helpsheet - things to change based on how a site is configured, what features are enabled. It might work out that a search/replace symbol would even work, taking you to the most common things to change...
And then, the Manual, as it is now in general structure (but written with more examples), with extra stuff like Cookbook stuck in as appendices for now.
- 07 Mar 2002
"30 days in the hole..." Re: PeterMasiar
's "final authority on docs terminology": above, I handle day-to-day (or so) upkeep of TWiki docs, which includes keeping them in order by checking out contributions and answering questions if I can, or passing them on otherwise. I also rewrite and clarify, help others help with docs,...
The final authority
on everything - code, docs - is PeterThoeny
, who ultimately determines what's included in a TWiki distribution.
Feel free to either post questions below the line, or edit the body text if you're comfortable that your changes will be an improvement (that includes correcting typos and any other errors). Part of my duties is to check changes and diffs, so it's fairly easy to spot inline edits and check 'em out. There's a master copy of docs that final changes are transferred to as a safety filter.
Post a question first if you have a BIG change in mind, reorganizing chunks of pages or anything like that: common sense before RCS...
And answer questions as well, if you feel like it - I'm not consulting any rule book when I do! :>
- 07 Mar 2002
It looks like this page is only for me and MikeMannix
- I wonder if anyone else even bothers to read it WebNotify
alone is not as long as on Codev, so I suppose many people do not know about action here. so I added a link to here from CoffeeBreak
I know that we cannot possibly to produce full set of versions
of documentations. And we do not have to. Just couple pages as Guides for newbies, rest can be mixed. But let's make all other (non-newbie) pages scanable, distinguish parts for newbies, and advanced parts. If easy to see icon will show to a newbie which parts of a document s/he can safely skip, I hope s/he will be easier to seduce to read the other parts. Maybe some of them will. Maybe not.
I understand PeterThoeny
is final authority
But style of documentation is a style
, personal preferences apply. Everybody has some, but docs should represent a consensus, right? Do we want graphics icons as mentioned above
, so newbie can scan page and skip advanced features? This suggestion is not only from my experience: Jakob Nielsen's Alertbox article mentioned above How Users Read on the Web
says, users do not read
. Users scan
the page. To increase readability, pages needs be scanable, IMHO. Do we want to go this road? If yes, we need nicer icons that I produced.
And what about SimplerDefaultTemplates
: Do we plan to add some as default distribution? I hope so, and for BeijingRelease
, and soon: but then docs should talk in terms of them. I would like to have
link on top of the page and have it in docs. Most of alternative simplified templates have links on top, too. Also, are there any chance to get some nice SimplerDefaultTemplates
also here to TWiki.org site? It will be nice IMHO if newbie will wonder here, Twiki.org site will have familiar look as from default distribution?
Also, can I go ahead and change topic
in docs (if/when making other changes, of course)? I found my user confused about it. Do simple things needs be confusing?
- 08 Mar 2002
Peter, other people do use this page, we just take months to get around to it
I just wanted to comment that I have to change all instances of "in case" to "if" in order to convey the correct meaning. "In case... do ..." means you must always do this as a precaution, no matter what the current conditions. "If... do..." means do it in these circumstances only. Consequently I have staff doing disastrous things while trying to be thorough. I checked the intended meaning of each instance in the December 2001 docs and it was safe to do a global change from "in case" to "if". Obviously it must have the opposite meaning to someone, somewhere. I wonder if they'd understand "if"?
Also I change all instances of "ex", which means "previous(ly)", to read "e.g.", which means "example" or "for example". While misunderstandings could occur I have not seen them. Rather, it takes only a bit of head scratching to realise what it means, and then it is understandable but it appears dreadfully unschooled, at least where I come from.
I wanted to mention these two in case anyone else had similar impressions and linguistic needs. Oh I'm quite used to colour being spelled color, -ize instead of -ise, and other obvious easy to guess differences are fine, but I've not encountered these two particular confusions elsewhere. From the lack of comment from others, perhaps it's only me who finds it a problem.
- 29 Dec 2002
I like those icon graphics.
- 11 Jan 2003
Peter, a simple metadata field should be added to each page in the TWiki web describing if it goes into the official release or not. Absence of this field assumes that it will not. The presence of a positive result in the data of the field should automatically put a warning at the top and the bottom of each page. The Comments line and end-include can be done automatically I can test out some of this in the Sandbox web if you like. This is obviously for CairoRelease
, not now.
- 23 Jan 2003
This is a good idea Grant, inclusive is better then exclusive. Yes, let's do that for Cairo. It will work for all but a few topics that cannot have any text added like WebRss
- 25 Jan 2003
I've put a reference to this topic on DocRequest
which is now refactored with forms for the new workflow.
This topic will have to be refactored too so as a start I've struck out some lines in #2_0_Developer_Documentation
and added replacement text.
I'm not sure what to do about section #3_0_TWiki_Docs_Final_Editing
It looks like the new workflow doesn't provide the same easy overview of which features still need documenting.
Perhaps we could stick to the convention of putting DocsToDo
in the OutstandingIssues
field and generate a search from that?
- 03 Feb 2005
The convention of putting DocsToDo
in the OutstandingIssues
field sounds like a good idea.
- 04 Feb 2005
A small thing that I think needs to be added here due to new convention of storing archival copies of release versions of TWiki web (e.g TWiki01
, etc.) is that references to other topics within the TWiki web should not
specify the TWiki web since these links either break or are incorrect when the web name is changed to TWikiXX.
- 15 Feb 2006
My company (a software developer) has just decided to start using TWiki for documenting enhancements to our software. I'm concerned about the apparant lack of the ability to print periodic hard copies of enhancements done between certain points in time but am otherwise feeling very positive about our choice to start using Twiki. Does anybody know of any people who are generating hard copies like this?
- 04 Mar 2006
Please ask support questions in the Support
- 04 Mar 2006