Uploaded image for project: 'Confluence Data Center'
  1. Confluence Data Center
  2. CONFSERVER-24972

Document the markup for macro names and parameters - both wiki markup and the new storage format

    • We collect Confluence feedback from various sources, and we evaluate what we've collected when planning our product roadmap. To understand how this piece of feedback will be reviewed, see our Implementation of New Features Policy.

      NOTE: This suggestion is for Confluence Server. Using Confluence Cloud? See the corresponding suggestion.

      1) Wiki markup

      We need to restore the documentation of the wiki markup for macro parameters. This information exists in the Confluence 3.5 documentation, but people need it in Confluence 4.x too.

      See comment here:
      http://confluence.atlassian.com/display/DOC/Working+with+Macros?focusedCommentId=279511378#comment-279511378

      Anonymous

      Please can we have the 3.5 User's Guide back? It contained so much more useful information. For example:

      This page (Working with Macros) was in a sensible place. Now I find it under "Customising Confluence"??
      The Index was not just a bunch of labels. Who knows what labels you've used?
      Macro parameters were given in detail, with examples of syntax.

      Your tech writers are trying to be too clever by half. I speak as a tech writer...

      And Sarah's reply:
      http://confluence.atlassian.com/display/DOC/Working+with+Macros?focusedCommentId=279511414#comment-279511414

      Sarah Maddox [Atlassian Technical Writer]

      Hallo anonymous

      I'm sorry that you've been having trouble finding the information that you need. I agree with you that this page (Working with Macros) was in an odd place. I've moved it under the section called "Creating Content". The technical writers spent a fair bit of time rearranging the table of contents in time for the Confluence 4.1 release, in the hope that it would be simpler to follow. So feedback like this is useful.

      I think the index in the 3.5 guide was the same. It's possible the Confluence user interface that is making it look different, and more like a bunch of labels. In previous versions, the labels were displayed as simple links, whereas now each label is a big block. But the functionality of the index is unchanged. The Confluence 3.5 User's Guide is still around: Working with macros. However, it's hosted on this wiki, which is of course using the latest version of Confluence.

      I think that the reason for removing the details of the macro syntax was that Confluence no longer uses wiki markup as its primary entry format, although you can still insert it on initial input. The macro browser UI gives the details of the parameters. I do agree, though, that in some cases the simplification went too far, especially given the fact that wiki markup is still a valid way of entering content. I hope to fix this, as soon as time allows. At the moment, my focus is on documenting the upcoming release. (smile)

      Cheers, Sarah

      2) New storage format

      We also need to document the macro names and parameters for the new storage format. See the page discussing the Confluence 4.x storage format:
      http://confluence.atlassian.com/x/twRnE

            [CONFSERVER-24972] Document the markup for macro names and parameters - both wiki markup and the new storage format

            SarahA added a comment -

            SarahA added a comment - W00t, hooray and hieperderpiep hoera ! All done: https://confluence.atlassian.com/display/DOC/Confluence+Wiki+Markup+for+Macros https://confluence.atlassian.com/display/DOC/Confluence+Storage+Format+for+Macros

            Bob Swift added a comment - - edited

            I know this is a documentation issue, but it would be really nice if the macro browser could show the underlying parameter name (optionally perhaps) so that it is readily available without going to the documentation . Another suggestion would be to allow a macro to define a link to more documentation on the specific macro. Links can be hard to manage in plugins, but it would provide a better user experience since some parameters are more complicated and need more detail that you can put in the description. Or perhaps a detailed information popup shipped with the plugin. If you look at the old notation guide information for some plugins, it was a very useful reference.

            Bob Swift added a comment - - edited I know this is a documentation issue, but it would be really nice if the macro browser could show the underlying parameter name (optionally perhaps) so that it is readily available without going to the documentation . Another suggestion would be to allow a macro to define a link to more documentation on the specific macro. Links can be hard to manage in plugins, but it would provide a better user experience since some parameters are more complicated and need more detail that you can put in the description. Or perhaps a detailed information popup shipped with the plugin. If you look at the old notation guide information for some plugins, it was a very useful reference.

            SarahA added a comment -

            I've published the documents with the information gathered so far. Only a subset of the macros are documented at this point, but it's worth publishing now so that people can benefit from what we have. I'll continue working on these documents in conjunction with Confluence 4.3 release work.

            SarahA added a comment - I've published the documents with the information gathered so far. Only a subset of the macros are documented at this point, but it's worth publishing now so that people can benefit from what we have. I'll continue working on these documents in conjunction with Confluence 4.3 release work. http://confluence.atlassian.com/display/DOC/Working+with+Confluence+Markup

            SarahA added a comment -

            Hallo Graham
            Thank you for your suggestions. I've already tried out Scott's cool plugin, and suggested to the dev team that we use auto-generated docs. The possible design of a solution is under discussion. Problems to solve include where to show the info (the admin UI is not the best place, because people other than adminstrators need the info), how to document nameless parameters, how to get the info about the parameter values and mandatory parameters, and more.

            In the meantime, we have decided that the wiki-based documentation will be useful now, and later in addition to any possible in-app documentation.

            SarahA added a comment - Hallo Graham Thank you for your suggestions. I've already tried out Scott's cool plugin, and suggested to the dev team that we use auto-generated docs. The possible design of a solution is under discussion. Problems to solve include where to show the info (the admin UI is not the best place, because people other than adminstrators need the info), how to document nameless parameters, how to get the info about the parameter values and mandatory parameters, and more. In the meantime, we have decided that the wiki-based documentation will be useful now, and later in addition to any possible in-app documentation.

            Graham Hannington added a comment - - edited

            Even if you decide not to generate the raw information for this documentation programmatically, then, rather than writing the presentation-quality documentation directly, consider writing documentation in a format (such as an XML vocabulary; it could even be Confluence XML) from which you then programmatically generate (via, for example, XSLT) the (expanded) presentation-quality documentation (which might also be Confluence XML). That way, you can keep the documentation source relatively concise, and make presentation-level decisions in a single location (such as an XSLT stylesheet), rather than having to make manual formatting decisions now that you might later regret (or wish to improve), but that are too time-consuming to change, because it would be too difficult to change the formatting across (dozens, perhaps even hundreds, of) manually created/edited pages.

            Graham Hannington added a comment - - edited Even if you decide not to generate the raw information for this documentation programmatically, then, rather than writing the presentation-quality documentation directly, consider writing documentation in a format (such as an XML vocabulary; it could even be Confluence XML) from which you then programmatically generate (via, for example, XSLT) the (expanded) presentation-quality documentation (which might also be Confluence XML). That way, you can keep the documentation source relatively concise, and make presentation-level decisions in a single location (such as an XSLT stylesheet), rather than having to make manual formatting decisions now that you might later regret (or wish to improve), but that are too time-consuming to change, because it would be too difficult to change the formatting across (dozens, perhaps even hundreds, of) manually created/edited pages.

            Graham Hannington added a comment - - edited

            Just a suggestion (this is entirely your call, no question): if I were doing this, I would first investigate the feasibility of generating this documentation automatically. Or at least, generating raw (or draft/skeleton) information that you could use as the basis for "presentation-quality" documentation; so that you could re-generate that raw information later, and compare it with a previous version of that information, to help minimize the manual effort required to keep the documentation up to date.

            Scott Dudley has already created a plugin that points the way. The output of that plugin could be enhanced/enriched with the use of additional Confluence API methods (as per my reply to Scott's comment announcing the plugin).

            I would be tempted to make the plugin output Confluence XML that could be directly added (via, say, WebDAV) to your Confluence Documentation.

            I'd probably also include in the automation the ability to "pull in" actual examples of macro usage. I can elaborate on this if requested. (Have you ever used doxygen?)

            Graham Hannington added a comment - - edited Just a suggestion (this is entirely your call, no question): if I were doing this, I would first investigate the feasibility of generating this documentation automatically. Or at least, generating raw (or draft/skeleton) information that you could use as the basis for "presentation-quality" documentation; so that you could re-generate that raw information later, and compare it with a previous version of that information, to help minimize the manual effort required to keep the documentation up to date. Scott Dudley has already created a plugin that points the way . The output of that plugin could be enhanced/enriched with the use of additional Confluence API methods (as per my reply to Scott's comment announcing the plugin). I would be tempted to make the plugin output Confluence XML that could be directly added (via, say, WebDAV) to your Confluence Documentation. I'd probably also include in the automation the ability to "pull in" actual examples of macro usage. I can elaborate on this if requested. (Have you ever used doxygen?)

            I'd like to cast a vote for this issue. We're currently evaluating Confluence for use in our company, so I'm a new user. Whilst the primary editor for a page/blog uses the new editor and associated macro browser, we're quickly discovering that other important areas of the application, such as templates, are still edited using wiki markup. It would be great if the wiki markup parameters could be restored, even if they're just dropped right at the bottom of each page. Having to trawl back through old versions of the doco is a pain. I've resorted to exporting and printing an older version of the doco ... which is counter-intuitive for a wiki!

            Deleted Account (Inactive) added a comment - I'd like to cast a vote for this issue. We're currently evaluating Confluence for use in our company, so I'm a new user. Whilst the primary editor for a page/blog uses the new editor and associated macro browser, we're quickly discovering that other important areas of the application, such as templates, are still edited using wiki markup. It would be great if the wiki markup parameters could be restored, even if they're just dropped right at the bottom of each page. Having to trawl back through old versions of the doco is a pain. I've resorted to exporting and printing an older version of the doco ... which is counter-intuitive for a wiki!

              smaddox SarahA
              smaddox SarahA
              Votes:
              7 Vote for this issue
              Watchers:
              9 Start watching this issue

                Created:
                Updated:
                Resolved: