This blog post summarizes the topics discussed at the Developer Center Call hosted on 19th July.
1. Hackfest Announcement
1.b Other Events
Libre Application Summit is happening from 6th to 9th September and Sriram is planning on coordinating a BoF-style session about the Developer Center (more info coming soon). If you are interested in this, please contact Sri (or comment on the Gitlab issue).
Shaun mentioned that Write the Docs Cincinatti happening on August the 18th to 22th could be a good venue for making a content plan, gap analysis and more. If anyone is interested in coordinating to make this happen, please contact me or write to the gnome-doc-list.
2. Developer Center Design Status
Allan has made an experimental tentative design in 2016 which tries to make something viable based on the existing developer content we have today.
Note: This design does not yet define details like the exact wording, the exact landing page contents, nor the exact visuals. We would need a web designer to take a look over this.
But Allans design puts the initial structure in place which can be used as foundation for new Developer Center and iterated upon.
- API Reference section
- Design Guidelines section
- Tutorials section
- Distribute section
3. Developer Center Prototype Status
3.a Website Prototype
Michael Hall has been working on a test instance based on Django which was previously used for the Ubuntu Developer Portal. Michael and Sri is currently getting a test instance hosted at GNOME in collaboration with Andrea Veri. For the previous Ubuntu Developer Portal, Michael had made a Django app which pulled in multi-language API references and updated the portal every night. The Django instance also supported multiple human languages with fallback behavior. It requires more server infrastructure but it could in the long run could support dynamic content such as Q&A for developers, comments on tutorials and code snippet uploading.
There was some discussion about whether a dynamic website system is needed or if a static website system designed for documentation could be enough for our needs. Evan Welsh was looking into using his GJS API Reference project in conjunction with Vuepress and will present a proof-of-concept for the next call.
EDIT: To be clear, there has not been made a definitive technological choice yet, but an evaluation will start soon.
3.b API Reference Prototypes
The current C API documentation as we know it, is hosted at the Developer Center.
HotDoc is a potential tool for source code inspection which should be investigated, but Philip and Evan (GJS developers) reported issues contributing to the project. Instead they wrote a DevDocs adapter which works by scraping G-I files. Patrick reported that the PyGObject API reference work using a similar scraping technique, but is based on Sphinx.
Allan argued that if necessary, we could in the very short-term try to stitch something together from different websites, so the initiative does not fall short due to the technical challenge in unifying these technologies. Attempting to solve everything from the start has been one of the reasons to that the initiatives has fallen short in the past.
4. Written Documentation Status
The current Human Interface Guidelines (HIG) and the Developer Tutorials are hosted in the gnome-devel-docs repository. The documentation is written in Mallard and edits are made by pushing updates to the gnome-devel-docs git repository. Allan still maintains the HIG today but the developer tutorials are in a mixed state between “still relevant” and “out of date” and lacks editorial control.
There was discussion about moving the documentation to MarkDown or Restructured Text which could also ease editing since Gitlab’s integrated editor supports it and Django supports it.
Next Developer Center Call
There is currently a framadate running to find the date for the next call, which will take place in 2 weeks’ time. The agenda so far is:
- Evaluation of Vuepress and Django test instances.
- Short-term plan for the API References.
- Short-term plan for documentation writing.
- Migration plan for Human Interface Guidelines / other content.
If you are interested in helping with the website or the documentation writing, join the next call or sign up in this Gitlab issue.