Suggested Features for DocProject - Contributing

Topics: Features
Jun 4, 2008 at 5:34 PM
Hi Dave,

as you asked me to give some hints why I prefer the SHFB atm.
  • one thing none of you have is a Visual Designer for the Conceptual Help. I would like to see something as the HTML Designer for the MAML
  • the Topic Designer is a little bit buggy (topic files, aren't save allways, so the toc is somtimes lost).
  • is the name of the Topic customizable. the editor eric released with his is neat, not perfect. a starting point, but no visual design.
  • would like to see a component the backtracks codeReferences from the topics, like pingbacks in blockposts. i thought about creating a buildcomponent, that solves this, but got not yet started
  • would be nice to see the xml comments of the code be editable by your cool designer like in the helpstudio
  • i dislike the restriction for not being able to switch my documentation style
  • is it possible to get only one porject type. I don't know the architecture, so only a question
feel free to contact me. After my holidays (I'm on vacation till end of june) I can get started with creating VSpackages (still doing tutorial stuff now) , I would like to support the community. Have you read my suggestion over at the SHFB discussion?

i would like to contribute anyway concerning the vspackage.

Jun 4, 2008 at 6:53 PM
Edited Jun 4, 2008 at 6:55 PM
Hi Rainer,

Thanks for the feedback. :)

> none of you have is a Visual Designer for the Conceptual Help
I'm currently working on a MAML editor that will be released as a VS 2008 package, eventually integrated into DocProject 2008, and also as a standalone library and WPF application.  A preview will be available in the next couple of weeks.

the Topic Designer is a little bit buggy
I fixed a bug for the next release that prevented changes from being committed.  If that's not the problem, then could you be more specific so that I can fix the bug?  Does it occur in the New Project Wizard or just the Topic Designer tool window?
You know that you can just open the content documents directly in the VS XML editor anyway, right?

FYI, detecting changes in the HtmlEditor control while it's hosted by VS was a real pain during development, so that may have something to do with the bug you're experiencing if it's in the tool window.  DocProject 2008 will have a custom editor for this anyway so whatever bugs there are now will no longer exist - but I'd still like to fix them :)

is the name of the Topic customizable
Yes, in the next release (1.11.0 RC), available within a couple of days.  There's a new Topic Properties window for conceptual topics that you can access by right-mouse clicking the topic in Topic Explorer and selecting Properties.  You can add raw HTML topics to the TOC now as well, although I don't recommend it over MAML, of course :)

When you create or import MAML topics two files are created: an .aml file that is the actual topic and a .cmp file that contains topic properties, such as MS Help attributes, index keywords and the topic's display title.  The .cmp is created with a dependency on the .aml so that it appears nested in Solution Explorer.  DocProject 1.11.0 RC also supports friendly names for conceptual topics instead of GUIDs.

(Note that DocProject 1.11.0 RC still supports typical .xml MAML topics like it did in previous releases, but the new model is recommended.  If you import your existing .xml topics into a new project they are converted to .aml and .cmp files automatically.)

Conceptual topics can now be stored in subfolders of Help\Topics as well, but Topic Explorer currently does not provide a way to create or import topics into subfolders; however, you can save your changes to the project, move files to subfolders, edit the relative paths in the Help\Settings\topics.xml file directly and then refresh the TOC.

would like to see a component the backtracks codeReferences
Interesting idea, but I don't see how it relates to either DocProject or SHFB.  This can be developed by anyone and used with each tool if desired.

would be nice to see the xml comments of the code be editable by your cool designer like in the helpstudio
That's on my todo list for DocProject 2008 :)

(Note that the MAML editor seems like it's going to be much nicer so I may use it for an XML documentation editor as well in DocProject 2008 instead of my HtmlEditor control, which is based on the WebBrowser control.)

i dislike the restriction for not being able to switch my documentation style
I have a feeling that most people who choose SHFB over DocProject have this hangup as well.  I have no intention of changing DocProject's architecture since to support that feature I'd be losing quite a lot of freedom and, therefore, DocProject's very high level of extensibility.  I also prefer the encapsulated project model that DocProject uses over NDoc and, I assume, SHFB.  This is another thing that some people seem to have a problem with, but I have no plans to change this behavior either.

Regardless, not once have I ever had the desire to change a style for a project after it was created.  But even if you want to, you can simply create a new project and import your topics and settings.  It's not difficult, but I can understand why people would shy away from that if they don't know where everything's stored in the project.  I was planning to write a help topic that describes the location of various settings but then I realized that I could automate the process, so in 1.11.0 RC (the upcoming release) there's a new step in the New Project Wizard that lets you choose an existing project from which all topics and various settings will be imported automatically into the new project.  I hope that helps :)

> is it possible to get only one porject type. I don't know the architecture, so only a question
Sorry but I don't understand what you're asking.  Could you please eplain?

Have you read my suggestion over at the SHFB discussion
Yes, thanks.

Just to be clear about my plans, I'm not going to abandon DocProject 1.x anytime soon.  In other words, DocProject 2008 isn't being written from scratch as a VS 2008 Package - most of the codebase is going to be the same, including much of the VS automation and MSBuild stuff, the build engine provider architecture and also many of the business objects that have been developed over the last year+.  There's no sense in reinventing the wheel, especially since DocProject's been out there in the community for quite a while now and is pretty well tested.  The MAML editor I'm working on will be integrated as well.  I'm missing the source XML documentation comments editor though, as you've pointed out, and I haven't started working on it yet either since it's not a priority.

I assume that SHFB is different from DocProject in several ways, so integrating it into VS and giving users a choice of which model they want may be a good thing.  So I'm all for Eric working on VS integration as well, although merging our two projects together is not such a good idea, IMO.

i would like to contribute anyway concerning the vspackage
Thanks for your offer to help.  I think I'm OK by myself for now, but if I need any help for DocProject 2008 I'll let you know.

- Dave
Jun 5, 2008 at 6:57 AM
Edited Jun 5, 2008 at 7:51 AM
Hi Dave,

thanks for your exhausting long answer. In the meantime I read your roadmap. Nice to see things going on. I'm looking forward, seeing your changes made to DocProject. So the plus on your side is the VSintegration. I'm leading our workgroup selecting a documentation mehtod. But there are a few points needed:

  •  a visual designer for designers or help authors. not everybody involved in documenting and help authoring is willing to learn such a rich and complex schema as MAML. They only want to use an editor (not my opinion. I like both things together. Getting the choice to use).
  • the backtracking (have to look into building a buildcomponent, then I'll do it on my own) can you imagine the benefit from not referencing from the xml in sourcecode to the conceptual help? the developer doesn't need to know anything about such links, and the docu (and therefore the assembly) don't needs to be rebuild everytime a topic is added
  • automatic builds (just for completeness. I know its allready supported)
The question for the projecttype was for web application, but I realliced there is a difficulty to combine both. You can delete this one from the list

The importfeature is nice, but not perfect. Using DocProject is cool, while your getting the features from the Studio, i.e. source control. Importing the documents to another project the changehistory will be lost. So it would be quite a nicer solution to have a tool deleting the old styles and placing the new ones in the project. The way how I can change styles is not important. The important thing for me is not to lose change history.

All other features sound great!

So it's a nip-and-tuck race.

My inital intention was to get started with VSpackage and contribute to the community, but I don't want to start from scratch an reinventing the wheel as you allready mentioned.

Jun 5, 2008 at 2:46 PM
Hi Rainer,

How do you propose that the backtracking feature would work?  I'm not sure that I fully understand your intentions, but if it's something that's usable I'd have no problem creating a standalone Sandcastle build component that does the job.

You bring up a good point about change history; I'll have to consider adding an upgrade feature for projects as an alternative to the new import feature.  A new work item will be created.  Although even if it's a pain you could propbaby create a new project and then bind it to an existing project in source control to retain the history for now.

BTW, nip-and-tuck makes it sound way too easy ;)

- Dave
Jun 5, 2008 at 2:52 PM
New feature request: 

Auto-upgrade DocProjects and DocSites
Jun 5, 2008 at 9:33 PM
Sounds great!

So here's the explanation for the backtracking feature. Do you know the methodology of pingbacks in weblogs? Where these autogenerated comments from other sites apper on your blog? the same thing I would like to see in the documentation!

So here is the example. Lets assume
You have an 100 assemblies to compile ...ah, a heavy load... lets assume 20. DocProject is configured in a separate assembly (of course).

There are severall architects documenting their architecture. a lot of developers documenting their code, and perhaps a bunch of conceptual help ... other help authors in the company don't beeing concerned with coding in their job.
So the help authors or lead managers would like to build a documentation to the existing code, maybee components. It would be nice to see a link to the additional topic A and B and C and ... (authored with the conceptual stile) in the SeeAlso section of the documentation from the function/propertie/namespace it belongs to, without modification of the xml-comments in code!

The next step would be to scan the SeeAlso links in the conceptual topic running down in the xmlcomment file to the origin this codeReference belongs to and place a SeeAlso to the documentation.

The Benefit: Sourcecode (the xml-comments)wouldn't be needed to be recompiled/recreated every time a new topic is added. The developer doesn't need to know about the additional topic.

Optional: adding a attribute to the codeReference allowing to block this type of pinging, or explicitely alow ping the source of the link?

To cut things short. A crosslinking feature that is triggered from the conceptual topic, maybee also from sourcecode. so you don't have to post a seealso, each time you create a relation to another method/propertie/and so on.

Any doubts left? Don't know if its a huge amount of work for such a component. We need one till the end of July! I'll get a go on it, when you tell me it's out of your roadmap plans.

Jun 5, 2008 at 11:17 PM
Hi Rainer,

It seems doable.  Tell me if this sums it up well:

Primary Objective: Add a feature that examines codeEntityReference elements in MAML topics and automatically adds links to the relatedTopics section during conceptual builds.
Secondary Objective: Add a feature that examines see links in XML documentation comments that point to conceptual topics in the same documentation set and add links to the See Also section during reference builds.
Additional Requirements: Extend the codeEntityReference schema to support a new attribute (e.g., autoRelate="true|false") that suppresses this automatic behavior in conceptual builds.  The default value will be enabled (e.g., true) if the attribute is not specified.

I believe that this can be done in the XSL transformations without a new build component.  You should add a new feature request to the Sandcastle Issue Tracker and I'll see about getting this into the next release of the Sandcastle Styles project.

- Dave
Jun 6, 2008 at 9:02 PM
Hi Rainer,

I misunderstood your original request.  I thought that you wanted the See Also section automatically generated from the links in the topic, but now I understand what you meant by backtrack - you want the See Also section of topics to be automatically generated from the links in other topics that reference it.

Sorry for the confusion.  This feature does require a custom build component since the XSL transformations only have information on a single topic, whereas this feature would require an index of all links in the entire documentation set.

I'll have time to work on this component in a couple of weeks, unless of course you'd like to create one sooner :)

- Dave
Jun 23, 2008 at 9:26 AM
Now you got it.

I wouldn't say create the See Also completely. Instead: Add the link from a topic to the See Also of the referenced topic. The See Also from the other topic should remain, not be overwritten.