Open XML SDK contains too few samples, isn't documented properly on microsoft's site and questions aren't answered on stackoverflow. about open-xml-sdk HOT 28 CLOSED

Hi @skrabbe001,

Which tools are you referring to? Are they from this list: Related Tools?

Specifically what samples are you looking for? We have samples in the documentation on learn.microsoft in addition to samples on our repo that haven't been migrated to learn.microsoft yet.

We are working to grow the available samples, but it is impossible to have a sample for every niche scenario, however, our sample documentation is open source, so you can also contribute a sample if there's something you think we should include.

from open-xml-sdk.

Which tools are you referring to? Are they from this list: Related Tools?

Yes.

Which samples are you referring to?

I am referring to the samples and "learn" that you provide in your reply. And I am referring to the open xml api documentation on microsofts site, ie. it providing litteraly no examples, and no context. Sometimes they show the raw xml. If I need to create raw xml, why would I need the SDK?

It means, that to create stuff, I have to read the spec. If I read the spec, I don't need the SDK.

But my my point is this:

You CAN NOT refer to stackoverflow, because the questions that need answering, aren't answered on stackoverflow. And it seems counterproductive to tell people to provide the samples themselves, that they are trying to get help writing. That's a catch 22.

Also, when a sample is provided, it should be crystal clear what version of the Open-XML-SDK the sample is intended for. For example, many version 2 examples doesn't work with version 3. And many version 3 examples for excel, doesn't work with powerpoint.

from open-xml-sdk.

So, what is the solution to this? I can see you have marked it as resolved, and then closed it.

Did you create a lot of new samples, and add examples (C# code) and context (what xml is created in what files) to the api documentation?

Did you add examples on how to query the context of xml in specific files?

How did you resolve it?

from open-xml-sdk.

@skrabbe001 you are asking a very open ended question here as well as being, frankly, rude to those working on a project you have never contributed to nor been involved in. @mikeebowen has asked for specifics regarding the tools or scenarios you want covered and you didn't provide any more details that would be useful. We can guess at what that would be, but it would be pointless and probably not help you.

You did have a specific ask in your main issue, but it's buried in between the lines telling us that we aren't doing a good job. Not a great way to solicit help, my friend.

Please keep in mind that this project is none of our full time jobs - it's something we continue to support and put time into in order to support the community. We ask that people respond in good faith to that.

As to some of your points:

Which tools are you referring to? Are they from this list: Related Tools?

Yes.

The related tools are a way of us exposing community projects that build on the SDK. You may check those projects out for your scenarios, but we do not support them

Which samples are you referring to?

I am referring to the samples and "learn" that you provide in your reply. And I am referring to the open xml api documentation on microsofts site, ie. it providing litteraly no examples, and no context. Sometimes they show the raw xml. If I need to create raw xml, why would I need the SDK?

Documentation is always lacking and if there are specifics, please open targeted issues for those. If you take a look at the rest of the API documentation on learn.microsoft.com, majority of them do not have examples - the API system we have there just doesn't work for that. Hence the docs at https://learn.microsoft.com/en-us/office/open-xml/open-xml-sdk which we have neglected over the years but are trying to bring them back into shape.

Raw XML is sometimes the best way to get something to work here (generally through a highler level model like XLINQ or similar), but we have seen many people use the SDK to handle the general package layout but manipulate XML themselves.

Another example is how to reuse the same embeded workbook for several different charts in a presentation. Does that work? Or must the workbook stream be re-read for each chart? Etc.

This is the only specific thing you have mentioned. In the future, I'd recommend starting with that as it's a clear ask, although not in line with the support we give here in the issues.

It means, that to create stuff, I have to read the spec. If I read the spec, I don't need the SDK.

Yes, we do expect that you may need to read the spec. We do not provide an object model over the spec. Feel free to ignore the SDK and just use the spec. The value of the SDK is to provide a bit of help with the bookkeeping of things required and a framework to build larger document manipulations on. It may not be for you if that is not your need

To be clear, I am the main contributor here and don't actually understand the spec - I rely on @mikeebowen and others for project direction regarding the spec. I understand .NET and maintain this project as I see the importance for many people. When I've needed to use the SDK, I use a related tool that builds on top of this to provide a more user-friendly model than the model here (which attempts to be 1:1 to the spec).

Also, when a sample is provided, it should be crystal clear what version of the Open-XML-SDK the sample is intended for. For example, many version 2 examples doesn't work with version 3. And many version 3 examples for excel, doesn't work with powerpoint.

The samples should generally work for both versions at compile time. If you have found issues there, please give back to the community by opening issues for each of those issues and we can work with you on specific issues. @mikeebowen has done a lot of work to bring those samples up to date with latest programming guidance but there is still a way to go. Telling us there are issues but not pointing to where will not get things to a better place and is unactionable our end.

You CAN NOT refer to stackoverflow, because the questions that need answering, aren't answered on stackoverflow. And it seems counterproductive to tell people to provide the samples themselves, that they are trying to get help writing. That's a catch 22.

I disagree - we can do whatever we want :) In all politeness though, we don't have the time to answer questions about spec usage for all scenarios. This project is to provide a mapping to the spec so that people can build against the spec in a strongly typed way. End of story. Stackoverflow has proven to get better traction for those kinds of questions so that we can focus on building a library that allows people to use the spec. However, if you have evidence to the contrary (such as statistics around questions asked vs answered), feel free to open an issue about it as a problem and we can discuss it.

So, what is the solution to this? I can see you have marked it as resolved, and then closed it.

Did you create a lot of new samples, and add examples (C# code) and context (what xml is created in what files) to the api documentation?

Did you add examples on how to query the context of xml in specific files?

How did you resolve it?

I'm completely lost as to what you are referring to by "this". This issue has not been resolved nor closed. You opened this issue and have pretty much focused on philosophical differences in how we should run the project, which you have not done a great job of convincing us to change. So far, there's nothing to do on our side.

If you disagree with this, that's fine, but it's the philosophy guiding this project. If you want our help, it would be wise to understand what the project is before going on a rant and telling us what we should and shouldn't do (or even better, what we can and cannot do). That is a quick way to shut down any helpful discussion.

from open-xml-sdk.

So, what is the solution to this? I can see you have marked it as resolved, and then closed it.

Did you create a lot of new samples, and add examples (C# code) and context (what xml is created in what files) to the api documentation?

Did you add examples on how to query the context of xml in specific files?

How did you resolve it?

Was this intended for #1571? If so, if you don't think it was resolved, feel free to reopen and give more details. There was no response for 3 months, so it was assumed you got what you needed and moved on.

from open-xml-sdk.

Was this intended for #1571?

No. I solved the problem myself. I confused the closing with this, as I thought it was closed ages ago.

This post is self contained, was created last week, has not been resolved and it is about:

• You can not refer people to stackoverflow, as only extremely few and simple questions are answered on stackoverflow. Often when they are answered, the reply ignores the question, and refers to an addon library that is build on top of the SDK.

And this is what should be fixed to remedy it:

• The api docs do not contain any examples, and they do not describe in which files they create xml fragments, and only rarely and randomly show some sample xml. This should be fixed.
• The api docs contains no code snippet examples. This should be fixed.
• The samples that are supplied (on github and microsoft-learn) don't cover any normal use case (barchart in powerpoint, how to create two charts that share the same data source, etc, etc, etc). Samples should be created.
• The tools that are refered to, are either not maintained anymore (prod tools) or don't work on all filetypes, or only covers a subset of openxml.
• It's not obvious which version of the Open-XML SDK the samples work with.
• I noticed you tell people to write the samples they are asking for help writing :D

Because of these problems, the time people have to spend using the SDK is far greater, than manually modifying the xml without using the SDK. I am currently just modifying and creating xml files, ignoring the SDK.

I do not understand, how any developer, can release a project in this state. Who is supposed to document the SDK?!

from open-xml-sdk.

The api docs do not contain any examples, and they do not describe in which files they create xml fragments, and only rarely and randomly show some sample xml. This should be fixed.

Feel free to create an issue to track this and let us know which APIs you feel should be expanded. The current pattern is fairly common in the .net space

The api docs contains no examples. This should be fixed.

This seems the same as above

The samples that are supplied (on github and microsoft-learn) don't cover any normal use case (barchart in powerpoint, how to create two charts that share the same data source, etc, etc, etc). Samples should be created.

The samples that exist exist specifically because they were a use case that someone in the past figured out and shared - it sounds like it just doesn't handle your specific use cases. If you feel like a sample should be created, feel free to create an issue to track that use case.

The tools that are refered to, are either not maintained anymore (prod tools) or don't work on all filetypes, or only covers a subset of openxml.

Most of them (as I stated above) are not part of this project and are community driven. If you feel that one of them doesn't make sense to include for whatever reason (it's not maintained, doesn't work, etc), please create an issue to let us know.

It's not obvious which version of the Open-XML SDK the samples work with.

As I stated above, please open issues for those samples as they should work with all versions and we can document/fix the ones that don't

I noticed you tell people to write the samples they are asking for help writing :D

If we don't have a sample, then most likely we'll ask for contributions if a good sample is figured out. We aren't here to write samples for everyone's use cases - we're a small team doing this as a side project because we see value in it.

Often the .Net examples don't include a "using" section, and several packages implement types with the same name, so it's ambiguous which type to use.

Great point - again, this is the kind of thing that would be good for it's own issue

@skrabbe001 I took time to respond to all your issues once and now I'm responding to more. Please engage on those responses rather than just reiterating everything and adding new things.

I'm going to close this issue as unactionable and too broad. As I mentioned multiple times, feel free to open individual issues for each of these things so they can be discussed and managed constructively.

from open-xml-sdk.

this issue as unactionable

Omg! That's a lie.

from open-xml-sdk.

Omg! That's a lie

Please be respectful. We're happy to engage with some of these things but this issue has too many issues and lacks detail (as described for each of your concerns) to be productive with.

btw GH is saying "closed as completed" - not sure where that came from, I just closed it due to the reasons I stated above.

from open-xml-sdk.

What is respectful about saying that it is unactionable to:

• not refer people to stackoverflow
• to write simple samples
• to document the work we do

from open-xml-sdk.

How is it respectful saying "the other .Net apis arent documented either, so neither we should we"./

from open-xml-sdk.

How is it respectful telling people asking for help, that they would not have to ask for if the SDK was documented, to write those samples themselves?

from open-xml-sdk.

That's not what I'm referring to - it's specifcally the line I referenced. You're taking things out of context and not responding to the responses I have given you.

All I'm asking is that you create an issue for each of the concerns you have so we can address them individually and with the proper attention to each.

from open-xml-sdk.

It is one simple issue: Don't tell people to ask elsewhere, when they ask how to use an undocumented SDK.

Everything I've written, is about that issue. It is the only issue. To solve it, requires documenting the SDK, creating samples, and not referring to tools that does not work. You want me to list each tool? It's ALL of them. You want to refer to an API page? It's ALL of them.

from open-xml-sdk.

Here is an example of how to document a framework / SDK / language:

https://en.cppreference.com/w/cpp

from open-xml-sdk.

Here is some stats from stackoverflow

Search: openxml hasaccepted:no
2,840 results

Search: openxml answers:0
1,025 results

openxml isaccepted:yes
2,512 results

Note that of the questions with an accepted answer, few of them are for the Open-XML SDK version 3.
Many of the unanswered questions are more than a decade old.

from open-xml-sdk.

We're not cpp - that is quite a comparison to attempt. Not even in the same league

So, if you only want to focus on whether or not stack overflow is the right place, we can scope this issue to that and only that.

from open-xml-sdk.

Note that of the questions with an accepted answer, few of them are for the Open-XML SDK version 3.

That's to be expected. It was released just a few months ago.

Many of the unanswered questions are more than a decade old.

sure, this project has been around for a long time.

Search: openxml hasaccepted:no
2,840 results

Search: openxml answers:0
1,025 results

openxml isaccepted:yes
2,512 results

Not sure how to interpret this. What is an acceptable ratio here for each of these? Absolute numbers aren't helpful to know if it's even reasonable and you're not including the total number of asked questions.

Do you think it would have better traction somewhere else? Where would that be? What are the stats in those places for answered questions?

from open-xml-sdk.

If we make a more specific search on stackoverflow, for example:

Search: openxml chart presentation isaccepted:yes

It returns these two questions:

Creating a power-point file reader ( pptx )

nodejs base64 parse returns a unexpected zip file

Browsing the answers, while rewriting the search to use openxmlsdk, presentationml or powerpoint, shows 0 questions regarding charts in powerpoint are answered (using the Open-XML SDK). It is not possible to create a new question, because the questions have already been asked, and a new question will be closed as a duplicate.

from open-xml-sdk.

Because of this, it's faster to (than using the SDK):

• create a powerpoint file without a chart and save it and unzip it.
• add a chart to the powerpoint file and save it with a new name and unzip it
• pipe all the xml files through a beautifier
• create a diff of the beautified files
• write your own SDK that adds a chart

The reason this is faster, is because the SDK is not documented.

from open-xml-sdk.

The reason this is faster, is because the SDK is not documented.

If you want that, please create an issue for that. You said you wanted this issue to be about why stackoverflow is not the place for question and answers about usage, not about documenting or reasons why openxml is hard. If you want to discuss something else, please create a targeted issue for that.

Please answer the questions I have asked here

from open-xml-sdk.

I feel like you don't understand the cause of the problem, which is an undocumented SDK.

Do you think it would have better traction somewhere else? Where would that be?

Here. And I've explained how to fix it, which you claim is off subject.

from open-xml-sdk.

The stackoverflow stats were an illustration. I showed how to go into detail here:

#1710 (comment)

from open-xml-sdk.

The resolution to not refer to stackoverflow, is to document the SDK here.

from open-xml-sdk.

Alternately it could be documented on the microsoft site, which is currently here. This is the API and samples I've refered to (including the samples on github).

from open-xml-sdk.

I've created a way to request API/scenario documentation when creating an issue. That would be good to at least track here

from open-xml-sdk.

Thank you :D

from open-xml-sdk.

Was this intended for #1571?

No. I solved the problem myself. I confused the closing with this, as I thought it was closed ages ago.

The only way documentation gets better is if you give back when you figure things out. Please provide a PR to update the docs to help guide future users to whatever helped you.

from open-xml-sdk.