User:Annew/AkademyWriting
Writing for UserBase
Who are our readers?
- People new to KDE
- Users with a specific problem, seeking help
Who are our Contributors?
- Users who want to contribute something to the project, and share their knowledge
- Developers who become aware of specific problems and want reliable information to be shared
- Developers who want to show-case their application - particularly if it's new or not so well known
- Developers who must write documentation and don't want to use DocBook to do it
What about Translators?
- Translators are a special group of Contributors
- Those with excellent language skills, contributing to i18n
- Those with excellent language skills, contributing to i10n
- Those with reasonably good language skills, happy to create on-line translations of pages
- Those with less good skills, who can copy and paste from old translations into new ones, but are also capable of distinguishing between recent translations and those too old to re-use.
Why do we need to consider Translators at the moment?
- We are not here to work on Translation issues at the moment - there is a separate workshop for that, but -
- To be a serious contribution we need to introduce standards.
- Our translators, particularly those involved in DocBook, are well placed to help us develop the standards
- If we get this right, Manuals can be written in the wiki, secure in the knowledge that DocBook manuals can be made from them.
Tools to help Standardisation
- http://userbase.kde.org/PageLayout - sets out elements of a new application page
- For sub-pages, bring in as many elements as are applicable, and use images wherever they help clarity
- For Manuals, create a front page to be your Table of Contents
- There is no way of automatically linking pages into a single ToC. You will need to create that page manually
- Create your pages in a tree-structure -
- App-name/Manual/ToC
- App-name/Manual/Getting Started
- etc...
- http://userbase.kde.org/Toolbox
- provides snippets of code to achieve the elements outlined in PageLayout
defines typography to make pages easily used in translation to languages or DocBook
There is some overlap in these pages.