GNOME Bugzilla – Bug 722498
[Docs] Create user documentation
Last modified: 2017-03-17 09:23:24 UTC
Having user documentation for 3.12 would be nice. I propose to write it during the DocFest that will happen by the end of january if no one has step up already. (btw that'd be great to have more components in bugzilla like "documentation")
Created attachment 333641 [details] [review] I started the documentation.
Review of attachment 333641 [details] [review]: Thanks a lot! This looks like a good first start! I've left some comments. ::: help/C/introduction.page @@ +6,3 @@ + <info> + <link type="guide" xref="index"/> + <revision pkgversion="3.20" date="2016-05-06" status="stub" /> Not too important, but the date should probably be August instead of May :) @@ +16,3 @@ + <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"/> + + <desc>An introduction to <app>Polari</app>, a clean, minimal irc client.</desc> Here and in other places, I would spell IRC in capital letters. @@ +22,3 @@ + + <p> + <app>Polari</app> is a simple irc client which integrates perfectly with gnome desktop and provides you distraction free window. It's GNOME in capital letters. Also, I'd say "the GNOME desktop". Not sure what "it provides you distraction free window" means exactly? Sounds like it needs some rephrasing, as I don't know how my windows can be distraction free. :) @@ +26,3 @@ + + <media type="image" mime="image/png" src="images/main.png"> + <p>A screenshot of main window of Polari(not connected to any network)</p> *the* main window. There is also a missing space between "Polari" and "(not". @@ +29,3 @@ + </media> + <media type="image" mime="image/png" src="images/main-dark.png"> + <p>A screenshot of main windo of Polari(not connected to any network) when global dark theme is enabled</p> Missing space (as before), typo "windo". Also, "*the* global dark theme". ::: help/C/network-connect-custom.page @@ +19,3 @@ + + </info> + <title>Connect to custom network</title> It's probably *a* custom network. @@ +20,3 @@ + </info> + <title>Connect to custom network</title> + <p>Its really easy to connect to a custom network too.</p> Typo "Its", but I would drop this sentence entirely. We generally hope that the user interface is "easy" however we don't need to tell the user every time, and especially if the user considers it non-easy so the user had to look up the documentation, then this might make the user feel a bit uncomfortable. :) @@ +26,3 @@ + </item> + <item> + <p>Click on the <key>+</key>on the top left corner.</p> Missing whitespace between "</key>" and "on". And it's probably *in* the corner. @@ +30,3 @@ + </item> + <item> + <p>In Add network window click the <key>Custom Network</key> button on bottom left.</p> If it is a specific window, it should be *the* window. Also, if "Add network" is the title of the window, this term should have markup. @@ +34,3 @@ + </item> + <item> + <p>Type the Server Address, Network name.</p> Are those terms shown in the user interface? If so I'd use markup here and probably and "and" instead of a comma. @@ +40,3 @@ + <p>(Optional) If you want to connect securely using SSL and your network supports it, then you can check the box.</p> + <media type="image" mime="image/png" its:translate="no" src="images/add-custom-network-config.png"/> + <p>Notice I've mentioned "<p>Notice I've mentioned" ? This is missing a closing tag, plus I guess it should be removed? Plus I'd avoid using "I" in general as the reader does not know who is I. @@ +43,3 @@ + </item> + <item> + <p>Click on <key>Add</key> button.</p> If there is only one such button, use the definite article. @@ +46,3 @@ + </item> + <item> + <p>Next you have to type Nickname and Real Name.</p> "Enter your..."? Also, if these are terms in the user interface, use markup. :) @@ +47,3 @@ + <item> + <p>Next you have to type Nickname and Real Name.</p> + <p>Note: Real Name is optional.</p> Above you used "(Optional)" as a prefix, here it is a "Note". Consistent style welcome. @@ +54,3 @@ + </item> + <item> + <p>Now type room name and password(optional).</p> Definite articles missing; missing spaces between "password" and "(optional)". ::: help/C/network-connect-preconfigured.page @@ +19,3 @@ + + </info> + <title>Connect to preconfigured network</title> Indefinite article missing, as network is countable. @@ +20,3 @@ + </info> + <title>Connect to preconfigured network</title> + <p>Its really easy to connect to a network.</p> Same comments apply as for the other file. :) @@ +26,3 @@ + </item> + <item> + <p>Click on the <key>+</key>on the top left corner.</p> Missing whitespace. @@ +30,3 @@ + </item> + <item> + <p>In Add network window select the preconfigured network.</p> Markup for "Add network", and it's only one window so a definite article is missing. @@ +34,3 @@ + </item> + <item> + <p>In Join room window, type the room name and password(password is optional)</p> Same as above - markup missing and missing whitespace. Also, other items finish with a full stop, here there is none?
Created attachment 333724 [details] [review] Corrected documentation and added "see also" links on bottom of pages.
Review of attachment 333724 [details] [review]: i think you accidentically included the "0001-Added-documentation.patch" inside the commit. :-) ::: help/C/introduction.page @@ +25,3 @@ </p> <media type="image" mime="image/png" src="images/main.png"> it looks like these screenshots were taken without having the 'gnome-icon-theme-symbolic' package installed on the system, hence the polari icon isnt' rendered. ::: help/C/network-connect-custom.page @@ +48,3 @@ </item> <item> <p>Click the <key>Add</key> button.</p> I think this step appears two times in the step-by-step guide on connecting connect to a custom network.
Created attachment 333730 [details] [review] Changed main screenshot file and did some corrections
(In reply to Bastian Ilsø from comment #4) > it looks like these screenshots were taken without having the > 'gnome-icon-theme-symbolic' package installed on the system, hence the > polari icon isnt' rendered. I didn't manage to really test these patches, but the symbolic polari icon isn't provided by adwaita-icon-theme-symbolic but polari itself (in data/icons/hicolor/symbolic) ... No idea what's going on off-hand though.
Oh, as I'm already commenting here - thanks so much for getting this started, it's very much appreciated!
(In reply to Florian Müllner from comment #6) > (In reply to Bastian Ilsø from comment #4) > > it looks like these screenshots were taken without having the > > 'gnome-icon-theme-symbolic' package installed on the system, hence the > > polari icon isnt' rendered. > > I didn't manage to really test these patches, but the symbolic polari icon > isn't provided by adwaita-icon-theme-symbolic but polari itself (in > data/icons/hicolor/symbolic) ... > > No idea what's going on off-hand though. I checked the screenshot and the symbolic icon is there now.
Hi Ankit R Gadiya, are you still working on it or I take up from here?
(In reply to roopa from comment #9) > Hi Ankit R Gadiya, are you still working on it or I take up from here? Hi, I'm not actually working on it right now, but I'd love to do more in it with little guidance.
Building on the included patches, I've written documentation for Polari. I've heavily borrowed from the Empathy IRC documentation. This should be reviewed by the Polari developers and I'll also ask the GNOME Docs team for a review as I haven't written any documentation for a few years. Any pages written used by Empathy retained their CC-By 3.0 license, all the new pages are licensed under 4.0. When I did a "git add ." it didn't add the Mallard pages for some reason, so there are two patches that will need to be applied. The two patches are: 0001-Add-Polari-documentation.patch 0002-Update-last-commit-Mallard-pages-weren-t-added.patch (Sorry about that)
Created attachment 347877 [details] [review] Add Polari documentation - update existing pages and screenshots
Created attachment 347878 [details] [review] New Mallard pages for Polari documentation
(In reply to Paul Cutler from comment #11) > Building on the included patches, I've written documentation for Polari. > I've heavily borrowed from the Empathy IRC documentation. This should be > reviewed by the Polari developers and I'll also ask the GNOME Docs team for > a review as I haven't written any documentation for a few years. Thanks a lot, Paul! > Any pages written used by Empathy retained their CC-By 3.0 license, all the > new pages are licensed under 4.0. > > When I did a "git add ." it didn't add the Mallard pages for some reason, so > there are two patches that will need to be applied. The two patches are: You can actually merge those two patches (commits) into one by running: git checkout -b temporary-branch git rebase -i HEAD~2 Provided that you want to merge the last two commits (better to do this in a temporary brach).
Created attachment 348012 [details] [review] build: Add the necessary buildsystem glue for docs The buildsystem bits we'll need, for squashing.
I've went through all the pages now, and overall this is looking great! There are just two comments that are real issues (main screenshot + removed UI), everything else are just possible additions (that can just as well be left to future revisions). It's quite exciting to get this in for 3.24 :-) So here's the list of what I spotted: - the screenshot on the introduction page is really bad: the logo is missing and the screenshot was taken with non-default settings (minimize+maximize in the titlebar) - irc-join-room mentions entering the password - that entry existed because it was in the mockups, but it never was hooked up to anything. Please don't document my laziness :-) (Kidding aside, the entry was killed off this cycle) - on the same page, I'm happy to say that the info box about repeating the steps for each room is outdated: https://git.gnome.org/browse/polari/plain/data/appdata/polari-join-dialog.png - a possible addition for the irc-start-conversation page are context popovers that have been added to all nicks in the chat log itself - network-connect mentions the password entry again - that page could also mention that you can connect to a network that uses non-standard ports by appending it to the address, for example irc.example.org:12345 - the overview page mentions "C hannels" (at the start of the last sentence) - for image pasting on the sharing page, regular copy+paste between file manager and polari is supposed as well
Created attachment 348031 [details] [review] build: Add the necessary buildsystem glue for docs (Updated for account-irc removal)
Thanks for the quick feedback. Everything in comment 16 has been updated and fixed. Commit a655535b10f2267482dc93b78277e87d1a6ca1cf in the docs branch.
(In reply to Paul Cutler from comment #18) > Everything in comment 16 has been updated and fixed. Awesome! I'll leave it to the docs team to give it another look-over, as far as I'm concerned everything looks great. After that, how do we proceed? Should I take care of squashing the branch into a single commit and test that everything works? (With proper patch author attribution of course)
Created attachment 348043 [details] [review] help: Add user documentation Provide documentation for the basic feature set, including how to join a network, joining a room, starting a conversation, sharing via paste and IRC commands. Some of the page are based on Empathy's IRC documentation and initial work from Ankit R Gadiya <ankit4922@gmail.com> All the content from the docs branch squashed into a single patch ...
Created attachment 348134 [details] [review] help: Add user documentation Merged the latest changes from origin/docs. This patch is also available as origin/wip/docs.
Attachment 348134 [details] pushed as 0b6dd78 - help: Add user documentation