KDE Documentation: Difference between revisions

Revision as of 10:14, 11 August 2010

Community home page of the KDE documentation team.

Lowering the barrier of entry of documenting

Collection of ideas to make documenting an integral part of any activity.

Multi-step documenting

Target is to enable as easy as possible way to input the knowledge one has. If quick and dirty it doesn't matter because another one will continue the work. Developer can make a braindump, say about feature, with no knowledge/interest of fine art of documenting. A non-developer documenter can edit this braindump with no need to prior knowledge about this feature because its in the braindump.

TODO:

way to connect edited contribution to maker of raw contribution
- maybe in edit summary when saving the edited version, like "Based on contribution by [[User:userName|userName]]"
  - Link to actual contribution, that is specific version of pastebin, seems overkill and in some cases wouldn't even fit into edit summary.
KDE Documentation/Pastebin - development version of pastebin page

User

Sample use case: A new user wants to know some little detail, say how to create application shortcut onto desktop. Gets answer, through trial and error, irc, mail, etc. Adds it into UserBase pastebin, from where editor with more knowledge can move it into appropriate place.

TODO:

create pastebin into UserBase
promote this workflow
- help menu to have link into some userbase & manual aggregate, both on- and offline which has "you can contribute" -section

Developer

Sample use case: Developer develops new feature and has no plans to document it. Makes braindump into TechBase pastebin. Someone else willing to contribute but with no knowledge about this feature can edit braindump into appropriate documentation.

TODO:

create pastebin into TechBase
promote this workflow

Promo wikis

Add into Wikipedia articles links to UserBase and Techbase, perhaps in some cases to CommunityWiki.

Template:

* [http://userbase.kde.org/Xxx Xxx] at [[UserBase]] - User documentation

* [http://techbase.kde.org/Projects/Xxx Xxx] at [[TechBase]] - Developer documentation

@@ Line 12: / Line 12: @@
 Target is to enable as easy as possible way to input the knowledge one has. If quick and dirty it doesn't matter because another one will continue the work. Developer can make a braindump, say about feature, with no knowledge/interest of fine art of documenting. A non-developer documenter can edit this braindump with no need to prior knowledge about this feature because its in the braindump.
+TODO:
+*way to connect edited contribution to maker of raw contribution
+**maybe in edit summary when saving the edited version, like "Based on contribution by <nowiki>[[User:userName|userName]]</nowiki>"
+***Link to actual contribution, that is specific version of pastebin, seems overkill and in some cases wouldn't even fit into edit summary.
+*[[KDE Documentation/Pastebin]] - development version of pastebin page
 ====User====
-A new user wants to know some little detail, say how to create application shortcut onto desktop. Gets answer, through trial and error, irc, mail, etc. Adds it into UserBase pastebin, from where editor with more knowledge can move it into appropriate place.
+Sample use case: A new user wants to know some little detail, say how to create application shortcut onto desktop. Gets answer, through trial and error, irc, mail, etc. Adds it into UserBase pastebin, from where editor with more knowledge can move it into appropriate place.
 TODO:
@@ Line 24: / Line 30: @@
 ====Developer====
-Developer develops new feature and has no plans to document it. Makes braindump into TechBase pastebin. Someone else willing to contribute but with no knowledge about this feature can edit braindump into appropriate documentation.
+Sample use case: Developer develops new feature and has no plans to document it. Makes braindump into TechBase pastebin. Someone else willing to contribute but with no knowledge about this feature can edit braindump into appropriate documentation.
 TODO: