changelog.md (5002B)
1 # Changelog 2 3 I'm documenting what I've done with the docs here for SFL. We will 4 delete this page once the new docs get accepted for docs.jami.net 5 6 7 - added "How to contribute to this documentation" 8 - refactored build guide (old build page should still be checked to 9 make sure I didn't remove anything important) 10 - rewrote introduction 11 - organized everything into a series of chapters like "General", 12 "Technical Reference", etc (every page can be accessed at any time 13 through the sidebar) 14 - removed handwritten tables of contents in pages and replaced them with autogenerated TOCs 15 - fixed grammer and spelling in FAQ; added all questions from the old 16 Ring FAQ that hadn't been added yet; added everything from the 17 website FAQ; combined some similar questions 18 - Old links were out of date and not very useful, but just in case, here they are: 19 - <https://web.archive.org/web/20181226012503/https://ring.cx/en/documentation/faq> 20 - <https://web.archive.org/web/20181226012541/https://ring.cx/en/about/privacy-and-anonymity> 21 - <https://web.archive.org/web/20180224163130/https://ring.cx/en/about/practical> 22 - old wiki link no longer works: <https://tuleap.ring.cx/plugins/mediawiki/wiki/ring/index.php?title=Special:AllPages> 23 - added some new questions to the FAQ 24 - added all relevant questions from the jami.net FAQ to this FAQ (we 25 should just have one document) 26 - made all headlines in the FAQ questions 27 - uploads/media are now located in the same directory as the document that refers to them 28 - if documents from multiple chapters refer to a file, the file can 29 go in the media/ directory 30 - renamed guides to "How to..." based on this advice: 31 <https://documentation.divio.com/how-to-guides/> 32 - Changed filenames to lowercase-with-hyphens, and use .md for 33 markdown and .txt for reStructuredText following this: 34 <https://documentation-style-guide-sphinx.readthedocs.io/en/latest/style-guide.html> 35 - all documents should only have one h1, which becomes the title of the document 36 - Moved most of the audio/video stuff into a separate 37 "troubleshooting" page; IMO these types of troubleshooting questions 38 aren't meant for the FAQ and they make it look bad. Some of them 39 should be deleted alltogether, for instance questions asking the 40 location of a setting which is just sitting there in the "general 41 settings" page. 42 - deleted UI and UX development page because it was useless and 43 completely outdated and all of the image links were broken (it can 44 be remade later if needed) 45 - deleted many broken image/file links from other pages 46 47 - moved many old pages into extra/ where we can start culling or 48 reintegrating them. plenty are just old drafts that can probably be 49 deleted 50 51 52 53 54 ## Notes 55 56 - FAQ is pretty large. I don't know if parts of it should be moved to 57 other pages 58 59 - the "General" chapter should remain the top priority; we should be 60 open to debate about which things to include or exclude, and we 61 should strive to keep the chapter complete and correct. 99% of users 62 won't read the other chapters. The first chapter is still an entry 63 point, so it counts as marketing as well as documentation. 64 65 - Linking guide: from the "General" chapter, only link to other 66 documents in the same chapter, except for the technical overview, 67 which can link to the technical reference. For instance, in the FAQ, 68 link to the name server heading of the Technical Overview, but in 69 the Technical Overview, you can link to the name server page of the 70 technical reference (there are a few exceptions, like linking to 71 "How to contribute") 72 73 74 - linking to other parts of the documentation summary: for whole 75 documents, use 76 77 ``` 78 :doc:`link title <relative-path-no-file-extension>` 79 ``` 80 81 for headings in documents, use 82 ```rst 83 :ref:`link title <full/path/to-doc-no-file-extension:headline title with spaces (case sensitive)>` 84 ``` 85 86 There are many examples in the [FAQ](general/faq). Please test 87 your links before submitting patches. TODO: add this information to 88 the contribution guide. 89 90 - markdown works fine but RST is better because then we can generate a 91 pdf of the documentation 92 93 94 95 ## TODO 96 - add notes about cross-referencing documents in the contribution guide 97 - make a more general "contribute" page (like https://jami.net/contribute/ ) 98 - edit the bug report guide 99 - go through the old build instructions page and make sure the new 100 chapter isn't missing something 101 - organize the technical reference 102 - delete some pages from the technical reference or the "Extra" chapter 103 - Improve PDF generation 104 - Internationalization 105 - other TODOs listed throughout the documentation 106 - Finish the Technical Overview in the General chapter (we're about halfway done) 107 - Finish going through the FAQ (I need to check the "Advanced" section 108 for spelling and grammar, and there may be some redundancy) 109 - Finish the "Feature requests" and "Troubleshooting" pages 110 - Someone need to write the DHTproxy guide (one user has volunteered 111 to give us a checklist after he does it)