Posts

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
Post a Comment
Read more

Season of Docs: Week 9 and 10

 Hi everyone, Sorry this one is reaching you a little late (and the post for week 10 a little early). I must say there hasn’t really been anything exciting to report! We’re at the pointy end of it now, all the content is there but now is the fun part (not...) - proofreading, editing, and more editing! Every page is at the final draft stage now, so please send me any feedback, any mistakes you find, anything at all. It should all be correct! I’ve played around with the look of the site, just a few colour changes and it’s looking much more on-brand. I also finally mostly figured out the PDF output. Who sets the default font to Times New Roman in this day and age?! I’d prefer the body of the text to be sans serif but I haven’t quite worked out how to do that yet... I’m away and out of reception for the next 4 days, but I’ll receive any messages on Discord once I’m back in civilisation.  As always, draft site at scummvm-documentation.rtfd.io  See you soon, Cadi
Post a Comment
Read more

Season of Docs: Week 8

  Hi everyone, It was a nicely productive week - due to rostering changes at my day job, I got an extra day off to work on this project!   This past week: •  Added port pages as I received information. Thank you to those developers who reached out and answered my questions, I really appreciate it! Also a shoutout to user @IlDucci  who was my guinea pig for the Vita, PSP and especially the Dreamcast.  •  Tweaked the FAQ; added a table of contents, general edits.  •  Proofread/edited most of the pages for consistency and compliance with the Google style guide. •  Completed a draft of the contribution guide for technical writers. With a few minor changes to be made, this will find its way into the wiki in the coming days. •  Redesigned the landing page with a handy Bootstrap plugin. I quite like the result but feedback welcome as always.  •  Fixed and then broke and then fixed the tables (again). Sphinx builds on Read the Docs can be a bit finnicky to say the least....  •  Pla
Post a Comment
Read more

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 her e . 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 “documenta
Post a Comment
Read more

Season of Docs: Week 6

We’re half way through the project! 6 weeks has absolutely flown by...  This is what I ticked off the to-do list this week: •  I re-arranged and tidied up the documentation. Each settings tab (or topic, in the case of audio) now has its own dedicated page. All the information you need to understand those settings are in one place; the first section on each page is an overview of the options, the second section goes into more detail, providing some background information and further explanation( or a how-to guide, in the case of the Cloud page). I hope that this way of presenting information is a little less confusing and easier to navigate - any feedback welcomed, as always!  •  I added a section regarding games on the main page; where to get them, where to find which data files you need, and where to find whether they are supported/compatible.   After a discussion with @Mataniko this morning, my timeline for the next couple of weeks is as follows: Week 7: Help: •  FAQ - pending feedba
Post a Comment
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
Post a Comment
Read more

Season of Docs: Week 4

It’s been a crazy week; sold the boat, moved in with my in-laws, found a rental, moved out of my in-laws’, and moved into the rental.  All in the space of about 4 days! I think it’s time for a nap! Nevertheless, I made a little progress this week, albeit not as much as I’d hoped: •  I combined the install pages for Windows, Linux and Mac into one, at the suggestion of @Mataniko. I agree that this is a better way to do it. •  First, second and third drafts of the Audio page. By far this is the most confusing subject for me, and I am forever indebted to @NMIError (and everyone who contributed this week) for all the information and corrections! I spent a fair bit of time on this one, as predicted, and there is still some information missing. I will continue with this next week.  •  First draft of the Cloud and LAN page. •  I took screenshots of the new v2.2 Launcher, although these are yet to be uploaded and changed on the Launcher/adding and playing games pages. I will most likely g
Post a Comment
Read more