Idea for Better Documentation
Issue #1248
resolved
So it’s been a longstanding bugbear of this project for me that the documentation is lacking, since it’s all on a blog in chronological order, and outdated constantly as improvements are made. And recently there’s been comments in other issues about “I’ll just need to remind myself to do X.” Also, the tooltips are getting very crowded as Thomas tries to insert multiple caveats.
In the past I recommended it move to a proper Wikia, but nothing ever came of it.
So I was thinking about another solution, when I remembered what the Godot game engine does, and then it hit me.
Why don’t we just include the documentation with the exporter?
Blender has a text editor, so the documentation can be loaded as a plaintext file and browsed right inside the program. It can be kept up to date alongside the exporter’s code. Rather than huge tooltips, operators can have unique identifiers that can be looked up with the text editor’s search function. If something needs to be added or updated, we can simply open an issue on here since it is technically part of the exporter.
Comments (31)
-
repo owner
-
I’m afraid I’ll have to agree with Thomas.
I personally find that the current Stable 1.6 documentation while indeed “far from perfect“, is more than adequate in detailing and describing the available tools and options, and honestly way more than expected for docs maintained by a single person. From those two links, as a casual Blender user, I’ve rarely gotten lost on an issue that’s not explained on the docs. What little confusion I do come across, is usually cleared up by a few minutes of issues browsing.
I don’t think the docs being outdated is quite accurate from my perspective as an user, since I understand that they are meant for the Stable version - I would never expect detailed docs on features still in development. And I think there’s little value in extensively documenting the Dev version since improvements are as you say “constant“.
Just my two cents, I’m perfectly happy with how the docs are handled currently, and I actually find the caveats in the tooltips illuminating at times and usually furthering my knowledge around those surrounding topics, but I do understand that might seem bloated to some.
Wiki does sound nice, but I’m honestly not quite sure how much of an improvement that’ll be over the current blog list, since they are already separated by topics, each post with relevant links to other topics - it already feels like a wiki to me.
I’m sure plaintext with in-app searching might prove helpful to some users, but I personally can’t see it being an improvement over a simple link to the blog list, with all the baggage it’ll put on the back of this project. And if trying to replicate what the blog list has right in blender, with its orgnizations and illustrations, seems a bit too much of an undertaking to me - reminding me that there’s probably a reason why every add-on I’ve come across has off-site documentation.
Thanks as always, Thomas and Midnight Arrow, and everyone contributing. I appreciate you all a great deal! Just wanted you to know that :)
-
reporter
@Thomas
I think that list could be made more prominent, because in all the time I’ve been reading the blog I have never seen it once. That feels like it should be linked-to from the header.
I understand this is a hobby for you, but I do have a financial stake in this, so when descriptions of what buttons do on the blog are outdated or missing then it feels like I’m wasting money, sorry.
That’s why I suggested a wiki in the first place--since it’s a collaborative platform, then multiple people could contribute to it.
@ Philly Q
I don’t find the separation between “stable” and “development” useful. Every time there’s an issue, the response from anybody (myself included) is “use the latest development version”. The stable versions, in my experience, lack important functionality corrected by bug reports/enhancements here such as Rigify bugs and material conversion (though since I don’t use converted materials anymore, that’s probably not an issue now.)
As I said, I’ve never once seen the master list of posts, so maybe it’s just a case that I haven’t been using the correct search terms. However a quick test shows that “Optimize Pose for IK” turns up no hits, despite being in the stable branch and being essential to successfully converting to Rigify. There’s no “Finishing” section in the blog post list, so how is somebody supposed to figure out what it means from the documentation alone?
-
I absolutely can understand the frustration. I myself had been using the dev version ever since I discovered it and with it being compatible with newer versions of Blender - so I’m a bit of a hypocrite in that regard, although I believe my point of user expectation still stands.
I felt it was an important distinction to make, even if it’s not practically “useful“ to those using the dev version. Documenting takes time and effort - and I felt the wrong impression was given that it was due to a lack of trying, and not for the reasons I assumed previously (Thomas can of course correct me if I’m wrong).
Also, you can find the “Finishing Section“ in the second list where all the panels are broken down, as well as a section on “Optimize Pose for IK”:
Second list is right below where you click for the 1.6 Download link on the “DAZ Importer Version 1.6“ tab - it was the very first doc list I encountered and been using ever since.
I too hope that there’s enough people knowledgable and motivated enough for Diffeo to have a Wiki, so that some weight can be taken off Thomas' shoulder. But I’m as green as they come - I’ll be grateful either way.
-
I tend to agree with Philly that the docs are good enough, though they require some time to find things but this is normal since diffeomorphic is quite complex, the easy import is the best option to start from. I also agree with Thomas that a inline text based help would be horrible, but there’s the zipped version of the docs for local use. There are also nice contributions on youtube. Then if anyone wants to convert to wiki there’s nothing to stop it.
As I understand it the general idea is to add notes in the blog for new important features in the dev version, then update the docs when there’s a new stable. If there’s something missing let me know I can help with the blog.
-
reporter
I’ve discovered a massive flaw.
The manual pages (the ones with “/p/” in the URL) do not show up when you search the website. Only the actual blog posts show up. So if you search for “Optimize Pose for IK” (or even just “optimize”) via the search bar, you get no results. Which may be one reason why I find the documentation very lacking, since I often use that to locate things.
@ Thomas
Is there any way to force the documentation to be visible when searching?
If not, that just reinforces my belief that blogging software is inadequate for technical documentation.
-
repo owner
The actual manual pages can be reached from the front page, http://diffeomorphic.blogspot.com/p/daz-importer-version-16.html. Similar to the front page of a wiki. Trying to reach pages by searching is not a good idea, since the outdated docs for previous versions are still there.
-
reporter
“Trying to reach pages by searching is not a good idea, since the outdated docs for previous versions are still there.”
That is what I’ve been saying all this time, yes. I understand this is a hobby and you’re probably busy with other things, but from an end-user perspective I’m sure you can understand how counter-intuitive and confusing this is? Having a search bar on the documentation website that doesn’t actually search through the documentation? I’ve been using this exporter for almost a year now, and this is the first I’ve heard of this.
-
It seems the search bar goes by titles, that is for example “root directory“ finds the relevant posts, while “optimize pose“ doesn’t. I don’t know if there’s an option to search by content instead of by title.
-
repo owner
Well, I am going to review the entire plugin and docs soon for version 1.7, so it could be possible to move the docs to a new platform in the process. Provided that it is possible to copy-paste the old docs including illustrations to use as a starting point, rewriting the docs from scratch would be too much work. If it is possible to make local edits and then a git-style push would be ideal, since online editing can be laggy.
However, I know nothing about how to make a wiki, and where to host it. I did some googling, and it looks like Blogger doesn’t support wikis. Wordpress does through plugins, but that seems to come with a monthly fee, and I prefer to use free sites so my work is not lost if somebody misses a payment (that happened at my job once). Are there other alternatives?
-
I know nothing about wiki too. Of course it is always possible to use the google search instead of the blog search, as in the example below. You may add a note in the main page that for extended searches it is possible to use google because the blog is limited to titles. I mean if there’s not some blog option to fix it.
site:diffeomorphic.blogspot.com "optimize pose"
edit. I also found instructions for extended search on blogger, but the “body” operator doesn’t seem to work. That said I’m not a expert on blogger at all just a casual user to help here if needed.
-
repo owner
Duh. It turns out that Bitbucket has a wiki feature, and that is of course the right place for it. I enabled it and copied some of the docs from Blogger. Text formatting can be fixed quite quickly in Textpad, but links and images are lost. Putting them back is going to take some time, but the pages have to be reviewed before the next release anywhere.
At this point I don’t know where to store the images. Adding lots of binary data is going to eat up space, and I don’t know what the limit for my Bitbucket account is.
Here is how the docs would look like if they are put on Bitbucket:
-
repo owner
The search function in Bitbucket appears broken, or it’s me who don’t understand how to use it. The tooltip is “Search slash”, but all I manage to find are repository names. So unless I’m missing something a Bitbucket wiki will not be searchable either.
-
repo owner
Did some more googling and the answer seems negative, e.g. https://community.atlassian.com/t5/Bitbucket-questions/Is-it-possible-to-search-through-a-content-of-wiki-in-my/qaq-p/703651
Moving to github could be an option, but it is unclear whether a github wiki would be searchable either. One user suggests using ordinary google search. https://stackoverflow.com/questions/12535602/search-for-a-keyword-within-a-github-wiki
Since the benefits of moving are unclear, the docs will stay on Blogger for the time being. However, the Bitbucket wiki appeared to be much more responsive during editing, which is a great plus but not enough to merit migration alone.
-
Would something like the Read the Docs be a valid option?
We will host your documentation for free, forever. There are no tricks.
I’ve seen quite a few add-ons use it for their docs, like this one Simple Cage Docs.
-
reporter
My issue was mainly that it seemed like Thomas wasn’t updating the blog posts containing the documentation as he added new features. Like “Select Hair by Width”. I had no idea what that was for since it never turned up in searches. Now that I know the documentation is totally separate from the blogs and doesn’t show up in search in the first place, I can go looking and see that it’s meant to delete flyaway hairs. So I’m not really opposed to it being on Blogger for the time being. But that info should be made clear to users with a stickied header or put in the “About Us” section or something, so they don’t spend over a year thinking the documentation is full of holes just because they use the search bar.
But I do think moving to a proper, searchable wiki is a good idea eventually.
-
Suggestion: Dokuwiki is a wiki engine which uses flat files rather than a database, so is very easy to set up on any web server. Perfectly adequate for serving up lightweight documentation. Very easy to back up since it’s just a set of files.
-
repo owner
I have played around with Bitbucket wikis a little more, and managed to include illustrations, and now agree that it has advantages over Blogger. It may not be searchable, but there are other benefits, like
- Storing the docs with the code is a natural place.
- Automatic backup with git.
- Easier to get a consistent look-and-feel; WYGIWYW rather than WYSIWYG.
However, at this point I am stuck because I cannot push local commits to the external master. The changes I have done so far have all been edited on site, but in the long run it is necessary to make local edits, e.g. in order to arrange the docs hierarchially. But those are probably just beginner’s problems.
-
repo owner
Now I figured out how to create subfolders with the online tool. This was the last main obstacle to migrating the docs to Bitbucket, I think. A snapshot of the dev version today becomes the new stable 1.6.2, but I hope to release version 1.7 rather soon - within a few months - where the main task is to upgrade the docs.
https://diffeomorphic.blogspot.com/2022/11/version-162-of-daz-importer-and-mhx.html
-
reporter
Excellent news. I think since it’s clearer the search bar on Bitbucket is for code, it should be more obvious that users will need to look through the docs manually, reducing confusion.
-
Personally I don’t notice much difference with the blog and this seems to me a waste of time. This is why I offer to help with the “cut and paste“ of the existing documentation so @Thomas you could focus on adding the new features, let me know if I can help. I know nothing of blog or wiki so I may need some instructions of what to do. Also I noticed the top menu doesn’t work, it links to files instead of linking back to the wiki pages.
My email if needed. ale.padone@gmail.com
-
repo owner
Thank you for your offer Alessandro. Just moving the old docs to a new place would indeed be a waste of time. However, one reason for making a stable release is to review the entire plugin and the docs, filling in missing info and fixing bugs that may have crept into tools that are seldom used. Version 1.6.1 was almost a year ago, and the docs were not updated for that release, so it is time to go over the docs anyway.
-
Ok I’m here if you need help.
-
@Diffeomorphic, @Padone, @Midnight Arrow
I want to share my 2 cents on this matter and i am thinking out loud here. Please feel free to ignore if its not possible or feasible.
But based on what i have seen, the one thing i feel that may be, just may be address atleast majority of the documentation issue.
I have seen lot of youtube tutorials on your addon, but what i really want to see is a full fletched multi-episode tutorial where someone can illustrate from start to end using your latest version of the addon on how to import a complex DAZ G8/G9 model with multiple textures, genitals, shells etc into Blender, go through the process of fixing all the issues like merging of textures, rigging, parenting etc and then animate the model.
This would help explain all the new features of the addon, like the jiggle physics, and probably address a lot of documentation issue.
I have been away for a long time and i was surprised to see the new jiggle physics. I have not tried the new version yet.
The only reason i mention this is because everytime, i try to go through setting up the addon and then finally come to the step of trying to rig, merge and parent the figure correctly with all the complex genital addons, i encounter some issue that stops me on my tracks. I then post the issue here as a ticket and then wait for days and weeks on end to get a solution.
We dont have to upload it on youtube because of YouTube's strict policies. Can it be uploaded or shared here?
Just one long or multi-episode videos on this would help a lot.
A picture speaks a thousand words, but in this case a video tutorial would speak a billion.
-
With all the diffeomorphic features available a complete series of video tutorials would be quite expensive in time to make them. Also features are always evolving so the videos are to be updated. Then personally I prefer the classic reference manual with text and pictures because a video I have to follow from the start to the end while a doc I can jump around and it’s much quicker to find what I need.
That said I can help with technical advice for what I now if anyone wants to make and maintain a video series.
-
@Padone
I understand you. But please understand, its difficult,time consuming and very tedious to go through such long documentation page by page. One page worth documentation can be covered by a video in may 2-5 minutes. Its going to be efficient. I dont mean to sound selfish or rude, unlike most people, and i speak for myself when i say that, the free time i have in my hands is limited. If a video tutorial on just getting a complicated daz model imported into blender and showing how to set it up correctly from start to finish would max take may be 30 to 45 min video? Wouldn’t that be leaps and bounds more efficient than the current documentation?
I am not saying to scrap the current documentation. The current documentation is extremely valuable and can be used as reference when the addon is updated. Ofcourse the addon will be updated. But having atleast one video tutorial related to one current/latest version of the plugin/addon will help in someway or the other.
My biggest gripe with the plugin/addon is that i always most of the time 99% encounter some plugin script issue or error related to some shell or genital addon i applied on the model. and this will be half way through the model setup. This error/issue will then halt the entire process and then i have to try some other variation of the model to hopefully fix the issue. And then when i create a ticket, i then wait for a long period, till some solution is offered. Correct me if i am wrong here, but when you import the daz model, you have to finish the setup of the model using the addon/plugin in one go one way. Its destructive process and each step cannot be undone. so i cannot save my progress like a blend file.
I am not telling to make a video for every update to the plugin/addon. But atleast one will help. The current documentation is extremely long, but helpful indeed, but video tutorial on this will indeed will go a long way. the video tutorial could be made and uploaded on the diffeomorphic website instead of youtube.
-
repo owner
The docs are not primarily tutorials but a reference manual, where you can look up specific tools. A major advantage of moving to a Bitbucket wiki is that the pages can be ordered hierarchially, instead of a big flat list of Blogger pages. This makes it feasible to make a single page for each button (or a group of related buttons), instead of long pages covering many tools.
If you look for video tutorials, there are several available from other people. A google search for "diffeomorphic daz tutorial" came up with many links, including
https://www.youtube.com/watch?v=bB21GupO6OM
https://www.youtube.com/watch?v=a2mmjcs16zE
https://www.youtube.com/watch?v=eooGNWW4X8A
https://www.youtube.com/watch?v=PhUiFz15TFc -
repo owner
Joseph, you are not the only one with a day-time job, you know. I have never made video tutorials and don’t want to spend time learning how to do it, but if anyone else wants to do it that is of course fine with me. Or you could try asking specific questions, either here or at the DAZ forums. Hint: “some script error or the other” is not specific.
-
Issue
#1280was marked as a duplicate of this issue. -
- changed status to resolved
The wiki has started.
-
😆😆😆😆😆….pls post when its Ready with all the new development build features …can't wait to try dev but I have to use it in a production environment so…
- Log in to comment
There is a list of blog posts sorted according to topic at https://diffeomorphic.blogspot.com/p/list-of-blog-posts.html. It is far from perfect, but it is what I use myself to find old posts. In the main documentation https://diffeomorphic.blogspot.com/p/daz-importer-version-16.html the tools are grouped by panel. Unfortunately, the docs have deteriorated because they have not been updated when things have changed. I hope to release a new stable version 1.7 when everything related to G9 has settled, and will go over the docs in the process. However, making a new stable release is a major effort and will take time.
It could be useful to rearrange the docs in a wiki format, but I’m not the one who is going to do that. Remember that this is a hobby project of mine. and I have already spent far too much time on it. If somebody else wants to convert the updated docs into a wiki that’s fine with me.
I’m more skeptical about making documentation in plain text. The illustrations are an integrated part of the documentation, and they will be lost. Plus that would be one more place to maintain.