search

getting-things-gnome / gtg

Getting Things GNOME! trunk
https://wiki.gnome.org/Apps/GTG
GNU General Public License v3.0
555 stars 164 forks source link

Update and extend the User Manual, automate publication of a readable online copy #243

Closed nekohayo closed 4 years ago

nekohayo commented 4 years ago

This is part archeology work, part updating, part invention, for whoever would like to work on documentation. Try to unify what you can find from:

...and:

nekohayo commented 4 years ago

About syntax, as a starting point, in https://github.com/getting-things-gnome/gtg/issues/210#issuecomment-570814121 I mentioned:

For the record, I do use [fuzzy dates / natural language parsing] regularly: now, soon, someday, but more importantly "tomorrow", "monday", "saturday", "samedi", "demain", "jeudi" (yes it works both in English and the user's translated locale, which is great); or even integers like "31".

I actually wish there somehow was something between "soon" and "someday" (I don't know what though) and that maybe we had even more formats supported, like "beginning of next month", "in 30 days", "beginning of next year, etc." but those are things that should go into a feature request ticket (if we're getting to that point I guess we're doing really really well).

(the 2nd paragraph is a feature request ticket to be created sometime that will probably link back to here)

vansia43 commented 4 years ago

I have finished analyzing these pages and noted that the majority need to be updated so I have begun working to include all of the new features and updated screen images.

Did a quick analysis of what was being displayed on: https://wiki.gnome.org/Apps/GTG/documentation. This is all included in the current user manual and will be updated as well. I think this page can safely be killed as it is already in the old user manual and currently available. The only piece that was not documented is:

language tags due defer
Dutch labels    
French tags échéance reporter
Italian tag dovuta posticipa
Malay tanda dijadualkan tangguh
Russian метки до отложить

If this is all still valid, it can be added into the user manual where it makes sense. This would check off one of the To Dos in #200.

As for https://wiki.gnome.org/Apps/GTG/FAQ, there is an FAQ page currently in the user manual. The manual has a question about backing up tasks and then leads to this page for more details. The only additional detail that this page adds is "GTG stores its data typically in ~/.local/share/gtg (The location depends on $XDG_DATA_HOME, read more about it). Backups are placed in the folder called backup. Try to replace your original file with the newest usable backup." I can add this to the FAQ when updating it doesn't make sense to include this in two spots.

On another note, the user manual contains separate topic pages for Design, Developer, and Translator credits. Does it make sense to keep these separate topic pages? This information is duplicated by the Credits in the About window and the AUTHORS file. I am thinking these pages should be left out once the manual is updated. There are a few other pages that I think can also be combined that are under the Get Involved and Advanced Topics headings in the user manual. A lot of the information duplicates the CONTRIBUTING page so a link to that page might be best so this isn't all duplicated. I'll see what makes the most sense once I get to those sections.

nekohayo commented 4 years ago

Thank you for working on this! My answers/guesses below:

¹: my very old notes (from 2011) about how to render a Mallard user manual using "yelp-build" (which is provided by the package "yelp-tools"), said this:

cd docs/user-manual/C/
yelp-build cache *.page

cd ..
mkdir -p html
yelp-build html -o html C/*.page

...looking at "docs/Makefile", I see it is supposed to do the same thing, if you run "make user_manual_html" in that directory, but it depends on the presence of a "sphinx-build" command, which is supposedly provided by the "sphinx" package but installing that package on my Fedora machine didn't make it work, so...

In any case, you don't have to worry about the user manual (and you don't have to / probably shouldn't commit the resulting HTML files if you generate them) because I can take care of that and it would be useful only for an eventual website anyway.

nekohayo commented 4 years ago

A wish for one aspect to clarify/document in "gtg-tag-color.page" depending on the outcome of https://github.com/getting-things-gnome/gtg/issues/308#issuecomment-626399995 :

vansia43 commented 4 years ago

I made some major strides on this over the weekend. So far a ton of restructuring and removing of old info. A lot of the pages are no longer needed such as credits, Installing the Daily PPA, and a lot of the stuff covered by the Contributors docs (which by the way look fantastic with your updates. Found the git tips really helpful). I ended up making one small topic in an Advanced section called Developer Resources, which just links directly to the appropriate contributor files if someone were trying to look for that type of information. This way, nothing is duplicated in the user manual. I don't know what is best practice for this but I ended up moving these topic pages to an outdated subfolder and have updated the revision history metadata to include an outdated tag. Sync services-related topics were also moved there since nothing is accessible at this time but can always be reinstated if that changes.

With regards to FAQs, I am actually going to just try and get rid of that from the user manual as a separate page. The questions are addressed or somewhat addressed within the help topics themselves. I think maybe adding a note attribute to highlight important info. would help certain points that might be FAQ candidates stick.

I stumbled across this page. Looks like our current legal.xml in the docs folder refers to ShareAlike 3.0. Assuming that I need to update to what is described on that page but wanted to be sure.

Getting close to a PR! :)

nekohayo commented 4 years ago

Hi there, replying to some of your specific questions:

I don't know what is best practice for this but I ended up moving these topic pages to an outdated subfolder

If some particular content is really dead and replaced/obsoleted by something else outside the manual, then it's best to just delete it completely (maybe as a standalone git commit) instead of moving it, because we can always revert it (especially if things are well separated in commits) or study the git commit history if for whatever reason we need to bring it back from the dead someday.

and have updated the revision history metadata to include an outdated tag.

Ah, I would not recommend doing that, in practice git tags are only used to identify commits that represent a software version release (like what you see if you go in https://github.com/getting-things-gnome/gtg/commits/master and then click "Branch: master" and then "tags"). A tag is a unique "pointer" to a particular commit / point in time, not the same thing as what you'd imagine as a topic tag in other software (like the bug tracker), so to speak.

vansia43 commented 4 years ago

Will do re: deleting the files.

Re: tags. Ah, sorry if that was confusing. By tag, I mean as part of the Mallard markup within the file, not through git. So for example, in any of the doc files, you'll see this under the Mallard info element:

<revision pkgversion="1301" date="2013-06-18" status="candidate"/>

For the status attribute, outdated is an allowable value (as well as candidate, draft, etc.) for any other doc contributors to see the status of the file.

nekohayo commented 4 years ago

Great work in that set of commits @vansia43 ! So, reviewing PR #318... Here are some feedback nitpicks and ideas, if you don't mind. Technically those could all be addressed later without blocking merging your existing branch, if you prefer to get it merged early and keep working incrementally.

From a high-level perspective, I feel there's an opportunity to reorganize the sections a bit (again not your fault, this was "like that" to begin with). For example, the distinction between the "Working With Tasks" and "Managing Tasks" section may be a bit arbitrary, and some elements of "Managing Tasks" like "Quick Add Entry" and "Understand View Modes" sound like things that would be more pertinent to a "main window" section... so then I'm wondering, would a hierarchy of topic sections like this work any better, in your view (this is just a rough/crazy idea...)?

...but that might be a more complex change/proposal, so that could wait for later if you prefer.

Overall, again, great work. Let me know if you'd like us to just merge it "as-is" as soon as possible, or if you want to rework it first, or something else (in case you're one of those who like to mess with "git rebase -i" to have a "flawless" history!)

P.s.: I think your name should go before mine in the info.py credits ;)

vansia43 commented 4 years ago

Thank you for all of the feedback.

A majority of these suggestions ran across my mind while updating and I realized I would never get the basic updates done if I kept restructuring. I started to deviate from the original structure a little bit but really just wanted to get a docs MVP out the door for now ;). You have also pointed out some things that I didn't even consider, so I am excited to improve this even more. Specifically on the version numbering for the old revisions I was totally confused as to why it was 1301. I probably spent more time trying to figure out if that was some Mallard styling or what. But yes, that will be its own update.

I am working on the meson.build file to add to this PR at this moment. Other than that, I think that I will need to work on these improvements in a different PR. I can open a separate issue for doc improvements -- whatever makes the most sense from your end. The images theme updates will be my number one update after this initial merge. I got so used to my dark Ubuntu theme I totally didn't even think of that! I will comment on the PR when I am done my final updates.

nekohayo commented 4 years ago

I suspected you probably wanted to get the "MVP" ready first, so yeah let's work toward merging what you already have there ASAP and then the rest of the "wish list" can be done later whenever you feel like it.

For screenshots: I've gotten my build working on Fedora now so I will also be in a decent position to make new official screenshots, with all the correct theming & fonts and hi-DPI (2x factor) and a standardized data set; I was planning to make them for marketing purposes anyway (see #274 for my idea of what I was planning to screenshot), maybe they can be reused for the manual, saving you some hassle?

vansia43 commented 4 years ago

@nekohayo I would like to tackle screenshots as my next task. When I run -s "bryce" I get some wild results: Screenshot from 2020-05-28 18-27-06

When I run -s "standard" I actually get data but I see what you mean where it is old (tasks due 3000+ days ago and large) Screenshot from 2020-05-28 18-30-23

First, I want to ensure that my tweaks looks correct (see the second pic where I turned off max/min window buttons).

Second, I can use the standard dataset, maybe adjust some due dates so it looks relevant but the rest seems fine enough unless you want something cleaner. Up to you if you want the marketing collateral to be an exact copy of the docs. Otherwise, please let me know if there is another dataset you create to take screenshots with. This way, I can access if we need to update anything else and you don't have to worry about doing that.

nekohayo commented 4 years ago

I think the "mmmmmmmmm" in Bryce's dataset are normal, they were probably real data that was anonymized. Seeing the filesize (1 MB), I'm now thinking it's a good dataset to keep around for performance optimization work & testing!

As for the standard dataset... yeah it seems to be the artificial one that was used for the original screenshots a decade ago. I'm wondering if we should change its example tasks to be closer to a GTD-style set of atomic tasks (which I think are usually very hierarchical because it's a chain of dependencies / "next actions"), or keep it like it is. Do you see any items that ought to be removed or replaced from that standard dataset for screenshottability purposes?

Also it could make sense for me to "git mv" to rename that "standard" dataset as a "screenshot" dataset just so it's clear what it is used for...

nekohayo commented 4 years ago

Side remark: I see that your icon theme shows a "star" icon for the "tags" button in the task editor, not sure where it is from, I don't think I've seen it while running on Fedora (GNOME/Adwaita themes) or Ubuntu. Just mentioning so you know, for documentation screenshotting purposes, that this is not the standard/official icon...

vansia43 commented 4 years ago

Not sure where it is coming from. I have everything on Adwaita .... Screenshot from 2020-05-29 13-14-20

Tried viewing when I sign in with Ubuntu at the start (and all tweaks are applied in Ubuntu) or when I sign in with GNOME at the start... not sure if that inactive shell field needs to be activated as well.

vansia43 commented 4 years ago

@nekohayo Did a little research regarding the tag icon and apparently the user-bookmarks-symbolic icon was once a star and then was adjusted. Not sure when this happened but I tried updating a bunch of things on 18.04 and could not update my icons to whenever this change was made. Long story short I ended up just getting myself onto 20.04 and I am all set now but figured it was worth mentioning.

As for the "standard" list, I understand that the whole idea of GTD is to really break out the "doable" tasks from the overall goal, and this dataset sort of does that. So in the first trip example subtasks such as "book what's needed" are broken out to accomplish "organize long trip." However, underneath that same "book a long trip" parent task, there is a subtask called "post pictures on the web" (something done after going on the trip). In this case, the subtask depends on the parent, so maybe when should remove some of the subtasks that don't make sense.

Some of the tags have no color and we may want to make sure they have a color or emoji associated.

There are also some old tasks such as"Listen to my new CDs", which I think we can a current update to.

Also, "buy needed groceries" is a subtask of "Prepare a nice party", but then there is a totally different, unrelated task of "buy some groceries." Thinking about the "clarify" step of GTD, I would make some of the titles more explicit to say "buying weekly groceries" or something that distinguishes the two tasks, especially when I do a search on the term "groceries" and want to know what groceries I need to get.

We need to show off the fuzzy due dates as well. None of these have start dates either, so pretty much everything is actionable at this point. We should also probably throw in some "closed" and "dismissed" tasks.

vansia43 commented 4 years ago

With #348 addressed everything mentioned in this comment:

Great work in that set of commits @vansia43 ! So, reviewing PR #318... Here are some feedback nitpicks and ideas, if you don't mind. Technically those could all be addressed later without blocking merging your existing branch, if you prefer to get it merged early and keep working incrementally.

...except for:

nekohayo commented 4 years ago

One other thing that came to my mind was the length and odd "shape" (visually speaking) of the intro text on the index page. The GTD quote may be more interesting to have into the "Getting Started with GTG" page, maybe as some sort of section explaining how the app can be used in various ways, either GTD-style or "simple grocery list" style, and is flexible to work with pretty much anything including ZTD (Zen to Done) or others (heck, Lionel even made his own method sometime). I also worry a little bit that a direct-quote featured so prominently like that on the front page might be a legal gray area that might almost be seen (or be claimed to be portrayed) as an association or endorsement, if you see what I mean.

There's no hard and fast rule there, but yeah, it's tricky to have the right intro length and relevance. That might be why most GNOME app user manuals sidestep the problem entirely by not having an intro at all ;)

vansia43 commented 4 years ago

Good point. It could also be something from a marketing perspective we could do like write some random articles on using GTG for different workflows... I was thinking about doing an article like this and how I have been using it to document the project on a personal blog (which needs its own revamp anyway.....)

nekohayo commented 4 years ago

Having redone the "standard" dataset into a new "screenshots" dataset (and pushed it to the mastert branch), I have published resulting screenshots (at least for marketing + "software center" purposes) in subfolders of "/gtg/" at the root of my personal website (the screenshots/appdata/ folder is a couple of symbolic links to the parent directory, for the software centers), including a cropped webp version for the wiki.

So I have now updated https://wiki.gnome.org/Apps/GTG with the main screenshot, and took the opportunity, since I also published the HTML version of the user manual in the "/gtg/user_manual" directory, to kill the old wiki "Documentation" page and link to the exported HTML user manual instead. At last, that wiki page is cleaned up!

vansia43 commented 4 years ago

Per #360 I have an additional TODO. Note to self:

vansia43 commented 4 years ago

With #360 I believe I have covered a majority of the high-priority changes needed before this release for the user manual. One thing that still remains is the subject of translations in the user manual. I have indicated throughout the new date parsing page that was created in #360 that date strings are translateable in your locale's language. In one of the earlier comments on this issue up above, I pointed out that one of the items on the GTG wiki site was a basic table of translated fields for the UI. I included that information in preferences.page when initially working on this issue because I was uncertain where to put it. That is probably not the best spot.

With the current translation work, I wanted to see whether that table is still relevant, where the best place to move it to would be (maybe this new date parsing page, even though it includes translations for the word tag? or, do we need to create something new...), and if it needs more added to it (since I see that the German translation is underway). Is maintaining this table worth it or are the notes that I included in the date parsing page sufficient at this point.

nekohayo commented 4 years ago

[...] In one of the earlier comments on this issue up above, I pointed out that one of the items on the GTG wiki site was a basic table of translated fields for the UI. I included that information in preferences.page when initially working on this issue because I was uncertain where to put it. That is probably not the best spot.

Yeah it was at https://wiki.gnome.org/Apps/GTG/documentation, and I have deleted that wiki page once you integrated that information in the user manual. I think the date parsing manual page is appropriate (or at least, anywhere in the manual is better than in the wiki :)

nekohayo commented 4 years ago

Merged Danielle's latest updates, also commit 2de694da that makes https://wiki.gnome.org/action/recall/Apps/GTG/FAQ?action=recall&rev=5 obsolete so I deleted that wiki page.

Should we keep the ticket here open, or should we consider the user documentation overhaul project "done" for pretty much all intents and purposes and therefore close this ticket?

vansia43 commented 4 years ago

@nekohayo The major overhaul is complete.

I am going to move that language table noted above into the date parsing page as it seems more relevant there since it isn't actually part of the Preferences UI. So expect one more PR with that and any very minor grammar fixes/final polishing as I want to look through everything once more before "code freeze" for this release. I am keeping an eye as best as I can on the commits and PRs to see if there is anything else I need to squeeze in here (UI changes etc.).

I don't think we need the ticket open still as the PR will literally be minor fixes. Your call, I am good with closing to check something else off.

vansia43 commented 4 years ago

@nekohayo when #386 is merged, we can close this. One issue though that I am running into is that when I try to open the help from the application, I see the the below error. I have been working from the source files this whole time so I cannot remember when I last opened it directly from the app, and if I had since upgrading to 20.04. Not sure if this is me or an actual issue.

image