Season of Docs: Week 7

 What I accomplished during week 7:


•  Started an FAQ. It’s got the basics, but I need more! Please keep the questions coming, I’ve only had two responses.... Link to Google Form here. The FAQ still has formatting issues and definitely some grammar/spelling issues, so don’t judge too harshly (yet). 

•  Created an “Other platforms” section, containing port-specific guides according to the agreed structure. I think they work quite well.

•  Replaced the GIFs on the iOS page. I’m much happier with how they are now. Feedback on the use of GIFs vs screenshots would be appreciated.

•  Added a “Release notes” section. 

•  Moved extra information out of the Settings pages and into a new “Guides” section. 

•  Got very, very confused by Git. At least now I (kind of) understand how to rebase. I think. Maybe. 


I had a meeting with @mataniko this morning, and we discussed how to go about setting minimum requirements for documentation moving forward. It’s been decided that a new “documentation guide” will go into the wiki. I still consider it to be a part of this project regardless of where it’s kept, since without it we run the very real risk of ending up with out-of-date documentation in no time at all. 


We also spoke about which ports to document next, and we decided to focus on those that are currently actively maintained. 


The last point we touched on was the FAQ. In addition to what’s there now (and in addition to other questions that come in from the community), we have decided to try using some “leading questions” to raise awareness around some of the newer features of ScummVM, such as Cloud and LAN functionality. 


Timeline for the next couple of weeks:


Week 8:

•  Documentation guide - Working with @mataniko, he will define what the requirements are from the developers with regards to documentation for new features. I will work on a guide (which will get any future technical writers coming in without prior knowledge of the project up to speed) - the style guide to follow, docs-as-code and github, commit requirements, and how to set up a local instance of Sphinx. 

•  Settings - Following a handy tip from @criezy, I’ll go through some of the code to make sure I’ve captured all the GUI options - some of this may end up in the port pages. 

•  FAQ - Continue working on this; more questions, easier navigation, and a general tidy up, proofread, edit...

•  Ports - Continue adding (maintained) ports. I’ll be reaching out to porters for information. I’ll also work to align the iOS and Android pages a bit better with the others.

•  Proofreading! Editing! Checking links! Ensuring docs are compliant with the Google style guide. 


Week 9:

•  Continue work on Ports and FAQ as I get information. 

•  Work towards final drafts of all pages. 

•  What will the PDF output look like?  LaTex customization. 

•  Start looking at customizing the theme; icon, colors, fonts, how it looks. This includes fixing table output (word wrapping issue). 


Again, I’m reaching out for help. There’s a lot of content on the portal now, we’re getting towards the end, and I NEED FACT CHECKERS. I don’t know what I don’t know, and I don’t necessarily know if I’ve explained something the right way. Maybe it isn’t clear, or I could explain it better. Be brutal. Tell me where the deficiencies are!! Also, I know many of you are not native speakers of English. I’ve tried to be mindful of this, but please let me know if I need to simplify something. I’ve been heads down in this project for a long time now, sometimes I get too caught up and can’t see the obvious. 


The docs are available here.


As always, see you on Discord!


Cadi


Comments

Post a Comment

Popular posts from this blog

Season of Docs: Project Report - Launch a Documentation Portal

  Project report: Launch a documentation portal •    The original proposal is available  here . •    The finished project, which will remain unchanged, is available  here . •    The live documentation is available  here . •   P ull requests available here  . The objectives The objectives, as set out in the project proposal: 1.    To produce high-quality, versioned end user documentation by consolidating large amounts of information from disparate sources and re-writing information for clarity, consistency, and completeness. Documentation should be easy to understand for beginners, without being patronizing to tech-savvy users. 2.     To create a documentation portal using a static-site generator. 3.    To future-proof end user documentation by creating templates and detailed how-to instructions for future open source contributors. The outcomes The completed documentation portal comfortably meets all the objectives: •    It is easy to follow, easy to navigate and pulls a large amount of
Read more

Season of Docs: Week 5

  I’ve had a very productive week, now that my personal life has calmed down a bit. I added v2.2.0 information, and finished off the audio and graphics pages. I also created first drafts of the new “saving and loading games” page, as well as contacts, bug reporting, known problems, games notes and copy protection pages.   A catch up with @Mataniko this morning has been very helpful to determine the path forward for the rest of the project, now that the bulk of the information is there. We spoke about what belongs in the documentation, and what doesn’t - and it was decided that things like “Games notes” from the readme, which I experimented with this week, will remain in the wiki, or will be added to the wiki if not there already.  We also spoke about the user experience when navigating the documentation, so for the next week or two I will be tweaking the structure to make sure that the user gets the best possible outcome: Week 6 Re-arranging the docs : •  The settings pages as
Read more