GNOME Bugzilla – Bug 711505
Write docs in Mallard
Last modified: 2015-01-26 16:03:23 UTC
Write documentation for gnome-photos in Mallard, and integrate it with the application.The docs will be licensed under CC-by-SA Unported 3.0 license, like all the other Mallard documentation.
Can we please have a "user docs" component for gnome-photos? It should have gnome-user-docs-maint@gnome.bugs as the default assignee (and QA too, if you like).
Created attachment 271686 [details] [review] First set of docs Sorry about the delay with this. I am merely committing and submitting the patch on behalf of Venkatesh, who has written up these pages. I helped him organise it a little better. I'll help him do it on his own from the next time.
Created attachment 272190 [details] [review] Help page added to view recent photos view-photos.page added to view recent photos
(In reply to comment #2) > Created an attachment (id=271686) [details] [review] > First set of docs Is this supposed to be shipped for 3.12, or just a work in progress for 3.13? It's missing adding the files etc to Makefile.am. "grid to open it. </p>" has a whitespace at the end.
Review of attachment 271686 [details] [review]: You should consider using translation markup in places: https://wiki.gnome.org/DocumentationProject/GDPGuide/Translations ::: help/C/index.page @@ +4,3 @@ + + <info> + <revision pkgversion="3.8" version="0.1" date="2013-03-05" status="review"/> We don't use "version" as the help version is closely tied to the pkgversion. @@ +8,3 @@ + <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"/> + + <title type="link">Photos</title> See https://wiki.gnome.org/DocumentationProject/GDPGuide/Website @@ +25,3 @@ + the file browser. You can use it to exclusively view image files present in + your computer or create albums, print photos and set favorites among your + photos in an interactive manner.</p> Maybe reword it to start more like "photos is awesome because…" instead of "photos is just another thing to do what you've always done"? ::: help/C/view-album.page @@ +18,3 @@ + <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"/> + + <desc>Find photos from your albums.</desc> This page doesn't tell me how to search for photos in albums. ::: help/C/view-favorites.page @@ +21,3 @@ + </info> + + <title>View photos marked as favorites.</title> This page should link to something which tells me why and/or how to mark a photo as favourite. @@ +28,3 @@ + </item> + <item> + <p>Select photo you want to open, or use the arrow keys to navigate to "Select the photo which…" ::: help/C/view.page @@ +26,3 @@ + computer, the <gui>Albums</gui> section contains your photo albums, and any + photo you mark as a favourite is placed under the <gui>Favourites</gui> + section.</p> Indentation? Photos section? I see Recent, Albums and Favourites. You call the sections tabs in other pages. I prefer tabs and that's what's also used in other apps.
Review of attachment 272190 [details] [review]: This page seems to lack a reason for existing: I find it clear that a tab which says "recent" and shows me photos is showing me recent photos. It is also the default view, so a user finds out about it the moment they start up the application for the first time. What could be interesting to talk about is what happens when photos are no longer "recent", assuming anything at all happens to them. You should also have a read of https://wiki.gnome.org/DocumentationProject/GDPGuide/Translations ::: help/C/view-photos.page @@ +18,3 @@ + + <title>View recent photos</title> + <p>To view recent photos:</p> Indentation, blank line between title and first paragraph.
Created attachment 272596 [details] [review] Build and integrate help/help button with photos. The patch creates a help button in the UI, and updates all the Makefiles to include the help.
Created attachment 272597 [details] [review] Translate string "_Help" in all po files Translate string "_Help" in all the po files present in Photos currently.
Review of attachment 272596 [details] [review]: Isn't this a duplicate of the patches in bug 727084 ?
Review of attachment 272597 [details] [review]: Isn't this a duplicate of the patches in bug bug 727084 ?
Comment on attachment 272596 [details] [review] Build and integrate help/help button with photos. Marking patch as obsolete since it has been submitted to a bug filed against general(as opposed to userdocs).
Comment on attachment 272597 [details] [review] Translate string "_Help" in all po files Marking patch as obsolete since it has been submitted to a bug filed against general(as opposed to userdocs). The above patch(marked as obsolete) and this one have been submitted to https://bugzilla.gnome.org/show_bug.cgi?id=727084
Created attachment 273054 [details] [review] Changes after Kat's review Changes: Kat's review + added favorites page and linked to it from view-favorites page. This also means two additional pages have been included in this patch. Thanks for the review Kat!
Review of attachment 273054 [details] [review]: ::: help/C/favorites-set.page @@ +25,3 @@ + + <p>Photos or albums can be marked as favorites from the + <gui style="tab">Recent</gui> tab or <gui style="tab">Albums</gui> tab.</p> "the Albums tab" @@ +30,3 @@ + <title>To label favorite items:</title> + <item> + <p>Select the <gui>Albums</gui> tab or <gui>Recent</gui> tab depending on "the Recent tab" @@ +34,3 @@ + </item> + <item> + <p><link xref="selection-mode-toggle#on">Switch on</link> the selection Where is this link pointing to? Do you mean 'href="help:gnome-help/selection-mode-toggle#on"'? @@ +38,3 @@ + </item> + <item> + <p><link xref="selection-mode-how">Select</link> all the items you want And this one? @@ +43,3 @@ + <item> + <p>To finish, select the button with the picture of a heart from the + toolbar at the bottom.</p> Not so keen on describing the UI: a favourites button in another theme could very well be a star. ::: help/C/favorites.page @@ +25,3 @@ + <title>Favorite photos</title> + <p>You can label photos or images that you particularly like as favorites to + store them for easy access in the <gui>Favorites</gui> tab.</p> Indentation? How do I do this? ::: help/C/index.page @@ +14,3 @@ + </info> + + <title>Photos</title> Missing logo, see https://wiki.gnome.org/DocumentationProject/Guide/Website @@ +17,3 @@ + + <p><app>Photos</app> can be used to organise and manage your images in an + engaging and personalized manner. In addition to creating albums out of Be more active here: "Use Photos to organize and manage your photos…" except having application names which are common nouns makes that sound a bit off, so stick to calling them images if you like. ::: help/C/view-favorites.page @@ +33,3 @@ + </item> + <item> + <p>Select photo you want to open, or use the arrow keys to navigate to "select the photo that/which you want…" ::: help/C/view.page @@ +27,3 @@ + open. The <gui>Recent</gui> tab contains images from your computer, the + <gui>Albums</gui> tab contains your photo albums, and any image you mark as a + favourite can be found in the <gui>Favorites</gui> tab.</p> This feels like you should have inline links to view-album and view-favourites (why is one of those plural and the other singular? ;) )
Created attachment 273550 [details] [review] patch to patch Venkatesh's help Aruna, please use the attached patch before making changes. I have separated out Venkatesh's work and pushed it to wip/help.
Review of attachment 272190 [details] [review]: The 3.12.1 release was due yesterday. Luckily it is late, so I was able to get this patch in on time. Otherwise, there would have been a broken Help menuitem in a stable release, which is a bad thing. Pushed to gnome-3-12 in commit 84bdf22fff28d15faec08486ac227e8110bab9e2 Rishi was very nice and said that he will make a 3.12.2 release for us later, so we have time to actually fix this help up.
Review of attachment 272190 [details] [review]: Sorry, wrong patch, this one is uncommitted. Rashi, can you rebase this patch on top of gnome-3-12 branch?
Review of attachment 273550 [details] [review]: This one is committed to gnome-3-12 in commit 84bdf22fff28d15faec08486ac227e8110bab9e2
Created attachment 274353 [details] [review] help: Don't refer to non-existent icon file Otherwise the build is broken.
Review of attachment 274353 [details] [review]: No need for this because Kat fixed the Makefile.am to point to the correct file.
Comment on attachment 272190 [details] [review] Help page added to view recent photos Thanks for the patch, Rashi. >+<page xmlns="http://projectmallard.org/1.0/" >+ type="topic" style="task" >+ id="view-album"> Is this template from the "view-album" page? ;) Change the id to view-recent, or something else related. >+ >+ <info> >+ <link type="guide" xref="view"/> >+ <revision pkgversion="3.12" date="2014-03-18" status="draft"/> >+ <desc>Open your recent photos.</desc> >+ </info> >+ >+ <title>View recent photos</title> What exactly does the Recent tab have? All the photos in the computer arranged according to most recently modified? Are photos only included from specific directories? One or two lines would help. >+ <p>To view recent photos:</p> Check indentation. This line would be indented exactly like <title>. I'd also leave a line space between <link> and <revision> in the <info> tag, like in the other pages.(These are not biggies though, just being thorough. :))
(In reply to comment #22) > What exactly does the Recent tab have? All the photos in the computer arranged > according to most recently modified? Are photos only included from specific > directories? One or two lines would help. Since this question has been asked elsewhere too, I will just answer here. The Recent tab shows photos from the user's computer (~/Pictures, ~/Downloads, and other locations added via Settings -> Search) and online accounts sorted in descending order of their modification time (most recent first).
Hi Debarshi, Can you please explain me how to add a specific locations photos in the Recent tab? Search gives me options only for adding All or Local photos. Thanks
(In reply to comment #24) > Search gives me options only for adding All or Local photos. You need *Settings -> Search*. ie. open gnome-control-center, go to the Search panel, click on the gear button at the bottom left and add a location.
Created attachment 274668 [details] [review] Help page to explain recent photos and view them Thanks Debarshi, Aruna for the reviews. I have updated the patch according to it. Please review again.
Created attachment 275883 [details] [review] The view-photos.page explains the location of recent photos displayed, steps to add more locations and to view the photos. As the review tab wasn't working for the previous patch, here is a fresh patch.
Comment on attachment 275883 [details] [review] The view-photos.page explains the location of recent photos displayed, steps to add more locations and to view the photos. >+ system locations like ~/Downloads, ~/Pictures, I wonder if these locations/paths should use <file> markup. >+ <p>Click on the gear button on the bottom right. You can select the >+ locations you want <gui style="tab">Recent</gui> tab to display.</p> Some word is missing here, probably a verb.
Review of attachment 275883 [details] [review]: This sentence, "The <gui style="tab">Recent</gui> tab displays photos from the local file system locations like ~/Downloads, ~/Pictures, other locations can be added as well and from the online or cloud collections." seems a bit long, and I would recommend splitting it into two sentences. I also agree with Andre in that the <file> tag would work well around ~/Downloads and ~/Pictures. Also, please use the active voice (e.g., "You can also add other locations, even cloud-based collections like Flickr or Facebook photographs, through GNOME Online Accounts.") The phrase, "The online accounts are sorted in the descending order of their modification time." is not relevant to the task at hand, and can be removed. I would put "To add other file locations:" on its own line. Finally, I also agree with Andre that it seems "You can select the locations you want <gui style="tab">Recent</gui> tab to display." is missing something. Thank you!!
Created attachment 276896 [details] [review] The view-photos.page explains the location of recent photos displayed, steps to add more locations and to view the photos. Thanks Andre, Jim for the reviews. I have updated the patch according to them. Please review again.
This bug is fixed with commit 6cc0b6014cc460f464c411dd0f3ccf0b5b4a4320 Thank you for your patch, Rashi. I did make a few, trivial updates to the patch before including it. Please have a look at the final update if you want to see what I changed.