Documentation
- Kurt Junghanns
What kind of documentation?
In general we need different types of documentation. These are: User-Documentation (UD), technical Developer/Development-Documentation (DD) and Project-Management-Documentation (PD)
Where is which documentation located?
InfAI proposes that UD will be decks on SlideWiki, YouTube videos and maybe a separate website.
DD is domain-specific and distributed. The developer website (slidewiki.github.io) is a technical introduction into SlideWiki (OSS) and must to be updated and extended by at least: Fluxible, database and data model content. It also links to the following websites and is the entry point for new developers. The GitHub wiki of the platform repository (https://github.com/slidewiki/slidewiki-platform/wiki) must to be filled with specifics about the frontend toolchain, style guides and more. A more general wiki (spanning topics) will be located in the repository of the developer blog (https://github.com/slidewiki/slidewiki.github.io/wiki). There must be at least pages about deployment, used tools, used frameworks, CI, CD, used technologies (OAuth, social login, Solr, NLP, …), architecture overview, data model to domain relationships, How To’s about how to use Github and who is the maintainer of which repo. As these are much information (that will fill several pages), only important information shall be tracked. The developer blog may be filled with announcements about new wiki pages and with slightly changed content from wiki pages (like deployment - How to deployment). Specifics of services have to be explained in their README.md files. If a service is more complex and needs more space, then its a concept/technology/tool which must to be explained elsewhere but could be linked to the service repositories README.md.
Why to use Github Wikis? Because they will stay online as long as the repo exists and Developers are already familiar with Github Wikis (will thus naturally search there).
PD is already in Confluence. The OSS and Open Course Ware idea/aspects must be revised and extended. → A long term question: Will Confluence stay online/active, even as the project has ended?
How should it look like?
The style of each page is predefined (md format for wikis, developer website and blog is already styled in md or simple html format). For pictures and diagrams, we propose to use Google tools. Created documents must to be stored in our Google Drive folders and could be linked to wikis, blog posts and more. By using Google tools, we emphasize to use the same styling.
If a special framework is used to visualize something (e.g. Reflux overview) the results should be linked to at least the above named websites (make it publicly available!) and should be available for everyone (not just interest groups).
We do not want to propose rules for UD - Proposals are welcomed and may be discussed separately.
Who is supposed to do what?
Fraunhofer and VUA should regularly manage responsibilities and check results.
InfAI will update the developer website, because the website was created by us.
Developer blog posts and wiki pages have to be created/updated by chosen developers. Ben (Fraunhofer) is the current maintainer of the Blog but InfAI and VUA may assist.
Again, for UD we do not want to propose any rules - Proposals are welcomed and may be discussed separately.
In the end, all decisions and detailed responsibilities have to be announced on the Google group SlideWiki 2.0 Developer's List.
Remarks
The hosting requirements (https://docs.google.com/document/d/10Vz8g1TTXwpCnAc4Xsf0qZWBPFV3O7oCeE65MrcWcLk/edit) have to be updated after each release and should be a wiki page under https://github.com/slidewiki/slidewiki.github.io/wiki .
The required skills for developers (https://docs.google.com/document/d/1dwWdHj_sNe1JSTuZhqB5oXm5FsD9EsRSDQm_CI6K9rE/edit) could be found on the developer website and have to be updated after each release.
The file about important links (https://docs.google.com/document/d/1tAmtft9lqLvqGTI9O_o4lzmg98tCEcCfyxSLNQ1asyI/edit) is just for intern discussions.
Presentations and pictures under https://drive.google.com/drive/folders/0Bxf24CK05c3SUTdMRFdUYklWYzQ could be mentioned and linked in the wiki pages.